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

# GET /admin/api/usage



## OpenAPI

````yaml /generated/openapi.json get /admin/api/usage
openapi: 3.1.0
info:
  description: >-
    Forwarding, management, portal and OAuth APIs generated from Rust types.
    Input and output schemas preserve their respective Serde contracts.
    Streaming events and WebSocket messages are documented alongside HTTP
    payloads.
  title: GPROXY HTTP API
  version: 4.2.1
servers: []
security:
  - bearer: []
  - anthropicKey: []
  - googleKey: []
  - queryKey: []
paths:
  /admin/api/usage:
    get:
      tags:
        - Management
      summary: GET /admin/api/usage
      parameters:
        - description: >-
            One of the caller's own keys. A key that is not theirs matches
            nothing,

            because the user filter is applied as well.
          in: query
          name: apiKeyId
          required: false
          schema:
            default: null
            description: >-
              One of the caller's own keys. A key that is not theirs matches
              nothing,

              because the user filter is applied as well.
            type:
              - string
              - 'null'
        - description: >-
            Bucket width for the trend. Absent means no trend is computed;
            present

            requires `toMs`, and without `fromMs` the buckets start at the first

            matching record.
          in: query
          name: bucketMs
          required: false
          schema:
            default: null
            description: >-
              Bucket width for the trend. Absent means no trend is computed;
              present

              requires `toMs`, and without `fromMs` the buckets start at the
              first

              matching record.
            format: int64
            type:
              - integer
              - 'null'
        - description: |-
            Admin surface only: the share of one credential's attempts. A portal
            refuses it for the same reason it refuses `groupBy: credential` —
            credential ids are the operator's, not the caller's.
          in: query
          name: credentialId
          required: false
          schema:
            default: null
            description: >-
              Admin surface only: the share of one credential's attempts. A
              portal

              refuses it for the same reason it refuses `groupBy: credential` —

              credential ids are the operator's, not the caller's.
            type:
              - string
              - 'null'
        - description: Inclusive lower bound on `startedAtMs`.
          in: query
          name: fromMs
          required: false
          schema:
            default: null
            description: Inclusive lower bound on `startedAtMs`.
            format: int64
            type:
              - integer
              - 'null'
        - description: Absent means no grouped cut is computed.
          in: query
          name: groupBy
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/Input_UsageGroupBy'
              - type: 'null'
            default: null
            description: Absent means no grouped cut is computed.
        - description: ''
          in: query
          name: model
          required: false
          schema:
            default: null
            type:
              - string
              - 'null'
        - description: ''
          in: query
          name: operation
          required: false
          schema:
            default: null
            type:
              - string
              - 'null'
        - description: |-
            Admin surface only: the share of one upstream provider's attempts.
            A portal refuses it, because it never shows a caller provider ids.
          in: query
          name: providerId
          required: false
          schema:
            default: null
            description: |-
              Admin surface only: the share of one upstream provider's attempts.
              A portal refuses it, because it never shows a caller provider ids.
            type:
              - string
              - 'null'
        - description: Exclusive upper bound.
          in: query
          name: toMs
          required: false
          schema:
            default: null
            description: Exclusive upper bound.
            format: int64
            type:
              - integer
              - 'null'
        - description: Ignored. See the type note.
          in: query
          name: userId
          required: false
          schema:
            default: null
            description: Ignored. See the type note.
            type:
              - string
              - 'null'
        - description: Administrative scope selected by the caller.
          in: header
          name: x-gproxy-admin-scope
          required: false
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Output_PortalUsageDto'
          description: Success
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Output_Envelope'
          description: Gateway error
      security:
        - consoleSession: []
        - bearer: []
        - anthropicKey: []
        - googleKey: []
components:
  schemas:
    Input_UsageGroupBy:
      description: Which column the aggregate is cut by.
      oneOf:
        - enum:
            - user
            - apiKey
            - operation
          type: string
        - const: model
          description: The upstream model name stored on the usage row.
          type: string
        - const: provider
          description: >-
            Group structured upstream usage by provider, with each provider's
            own quantities and cost.
          type: string
        - const: credential
          description: |-
            The same per-attempt cut as `Provider`, keyed by the credential that
            served each attempt: what each upstream account actually spent.
          type: string
    Output_PortalUsageDto:
      description: The caller's own usage over the requested range.
      properties:
        fromMs:
          format: int64
          type:
            - integer
            - 'null'
        groups:
          description: Empty unless `groupBy` was given.
          items:
            $ref: '#/components/schemas/Output_UsageGroupDto'
          type: array
        summary:
          $ref: '#/components/schemas/Output_UsageSummaryDto'
        toMs:
          format: int64
          type:
            - integer
            - 'null'
        trend:
          description: Empty unless `bucketMs` was given.
          items:
            $ref: '#/components/schemas/Output_UsageTrendPointDto'
          type: array
      required:
        - fromMs
        - toMs
        - summary
        - groups
        - trend
      type: object
    Output_Envelope:
      properties:
        error:
          $ref: '#/components/schemas/Output_EnvelopeBody'
      required:
        - error
      type: object
    Output_UsageGroupDto:
      description: One bucket of a grouped aggregate.
      properties:
        key:
          description: |-
            The grouping column's value. None is "the records carried none" — an
            anonymous request has no user, a failed attempt no provider.
          type:
            - string
            - 'null'
        summary:
          $ref: '#/components/schemas/Output_UsageSummaryDto'
          description: >-
            `truncated` and `scanned` describe the one scan every group came
            from,

            not this group alone.
      required:
        - key
        - summary
      type: object
    Output_UsageSummaryDto:
      description: Totals over the records a scan covered.
      properties:
        averageOutputTps:
          description: >-
            Output tokens per second of generation time, excluding first-token
            wait.

            Only records with reported output tokens, TTFT and positive
            generation time contribute.
          format: double
          type:
            - number
            - 'null'
        cacheCreation:
          items:
            $ref: '#/components/schemas/Output_CacheCreationDto'
          type: array
        cacheCreationTokens:
          description: Total reported cache writes across all retention periods.
          format: uint64
          minimum: 0
          type: integer
        cachedInputTokens:
          format: uint64
          minimum: 0
          type: integer
        cost:
          description: A normalized decimal string, `"0"` when nothing was priced.
          type: string
        currency:
          description: USD when any record was priced; None when none was priced.
          type:
            - string
            - 'null'
        inputTokens:
          format: uint64
          minimum: 0
          type: integer
        outputTokens:
          format: uint64
          minimum: 0
          type: integer
        quantities:
          additionalProperties:
            type: string
          description: >-
            Totals of reported media/tool quantities; keys are billable metric
            names.
          type: object
        reasoningTokens:
          description: Part of `output_tokens`, listed rather than added.
          format: uint64
          minimum: 0
          type: integer
        requests:
          description: >-
            Number of physical upstream calls, independent of downstream
            association count.
          format: uint64
          minimum: 0
          type: integer
        scanned:
          format: uint64
          minimum: 0
          type: integer
        truncated:
          description: |-
            The scan stopped at its row cap. The numbers describe `scanned`
            records, not every record the filters match.
          type: boolean
      required:
        - requests
        - inputTokens
        - outputTokens
        - averageOutputTps
        - cachedInputTokens
        - cacheCreationTokens
        - cacheCreation
        - reasoningTokens
        - quantities
        - cost
        - currency
        - truncated
        - scanned
      type: object
    Output_UsageTrendPointDto:
      description: One fixed-width bucket of a trend. Present even when empty.
      properties:
        endMs:
          description: |-
            Exclusive, always `start_ms + bucketMs`: the last bucket keeps the
            width of the others even when the requested range ends inside it.
          format: int64
          type: integer
        startMs:
          format: int64
          type: integer
        summary:
          $ref: '#/components/schemas/Output_UsageSummaryDto'
      required:
        - startMs
        - endMs
        - summary
      type: object
    Output_EnvelopeBody:
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message
      type: object
    Output_CacheCreationDto:
      description: >-
        Reported cache writes for one retention duration. None means unknown
        TTL.
      properties:
        tokens:
          format: uint64
          minimum: 0
          type: integer
        ttlSeconds:
          format: uint64
          minimum: 0
          type:
            - integer
            - 'null'
      required:
        - tokens
        - ttlSeconds
      type: object
  securitySchemes:
    bearer:
      scheme: bearer
      type: http
    anthropicKey:
      in: header
      name: x-api-key
      type: apiKey
    googleKey:
      in: header
      name: x-goog-api-key
      type: apiKey
    queryKey:
      in: query
      name: key
      type: apiKey
    consoleSession:
      in: cookie
      name: gproxy_session
      type: apiKey

````

## Related topics

- [GET /admin/api/usage/records](https://gproxy.leenhawk.com/api-reference/management/get-adminapiusagerecords.md)
- [DELETE /admin/api/usage/records](https://gproxy.leenhawk.com/api-reference/management/delete-adminapiusagerecords.md)
- [POST /admin/api/usage/records/delete](https://gproxy.leenhawk.com/api-reference/management/post-adminapiusagerecordsdelete.md)
- [GET /admin/api/logs/downstream/{id}](https://gproxy.leenhawk.com/api-reference/management/get-adminapilogsdownstream-1.md)
- [GET /admin/api/channels](https://gproxy.leenhawk.com/api-reference/management/get-adminapichannels.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.