> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rigbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Subject Usage

> Read one end-user (subject)'s AI spend over a rolling window, from inside the workspace VM.

<Note>
  This endpoint is served by the in-VM managed proxy at `http://172.16.0.1:9090`, not the public `api.rigbox.dev` gateway. It is **IP-attested** and scoped to the calling workspace's owner — you can only read your own subjects.
</Note>

See the [Managed AI Proxy guide](/guides/managed-proxy#per-subject-cost-and-budgets) for how subjects are attributed and enforced.


## OpenAPI

````yaml GET /rig/v1/usage
openapi: 3.1.0
info:
  title: Rigbox Managed AI Proxy
  version: 1.0.0
  description: >-
    The managed AI proxy reachable at `http://172.16.0.1:9090` from inside a
    workspace VM. It is **IP-attested** (no API key — send a placeholder
    `Authorization: Bearer managed-by-rigbox`) and exposes an OpenAI-compatible
    `/v1` surface over OpenRouter.


    This reference documents the multi-tenant metering surface: the settled cost
    returned on each response, per-subject cost attribution and the
    rolling-window read, and per-subject budget + rate-limit enforcement. The
    proxy is the *mechanism*; your app owns *policy* (which tiers exist, the
    amounts, the windows) and asserts the end-user ("subject") id over the
    IP-attested channel.
servers:
  - url: http://172.16.0.1:9090
    description: In-VM managed proxy (bridge-local, IP-attested)
security: []
tags:
  - name: Managed Proxy
    description: >-
      Per-subject cost metering, attribution, and budget/rate-limit enforcement
      for multi-tenant apps.
paths:
  /rig/v1/usage:
    get:
      tags:
        - Managed Proxy
      summary: Read a subject's rolling AI spend
      description: >-
        Per-subject AI spend over a rolling window, served directly by the proxy
        from inside the VM. Scoped to the calling workspace's owner — you can
        only read your own subjects, and subjects are isolated from each other.
        Attribution is forward-only: only calls made after this feature shipped
        carry a subject.
      operationId: get_subject_usage
      parameters:
        - name: subject
          in: query
          required: true
          description: >-
            The end-user id (the value sent as `X-Rigbox-Subject` / OpenAI
            `user`).
          schema:
            type: string
            example: tenant-42
        - name: window
          in: query
          required: false
          description: >-
            Rolling window: `30s`/`15m`/`5h`/`7d` or a bare number of seconds.
            Defaults to `86400` (24h).
          schema:
            type: string
            default: '86400'
            example: 24h
      responses:
        '200':
          description: The subject's usage over the window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubjectUsage'
              example:
                subject: tenant-42
                window_seconds: 86400
                credits: 0.00072
                credits_micro: 720
                input_tokens: 8
                output_tokens: 10
                requests: 1
        '400':
          description: Missing `subject` or an invalid `window`.
          content:
            application/json:
              schema:
                type: string
components:
  schemas:
    SubjectUsage:
      type: object
      description: A subject's aggregated AI usage over a rolling window.
      properties:
        subject:
          type: string
          example: tenant-42
        window_seconds:
          type: integer
          example: 86400
        credits:
          type: number
          example: 0.00072
        credits_micro:
          type: integer
          format: int64
          example: 720
        input_tokens:
          type: integer
          example: 8
        output_tokens:
          type: integer
          example: 10
        requests:
          type: integer
          example: 1

````