> ## 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/records



## OpenAPI

````yaml /generated/openapi.json get /admin/api/usage/records
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/records:
    get:
      tags:
        - Management
      summary: GET /admin/api/usage/records
      parameters:
        - description: ''
          in: query
          name: apiKeyId
          required: false
          schema:
            type:
              - string
              - 'null'
        - description: Records whose structured upstream usage matches this credential.
          in: query
          name: credentialId
          required: false
          schema:
            description: Records whose structured upstream usage matches this credential.
            type:
              - string
              - 'null'
        - description: ''
          in: query
          name: fromMs
          required: false
          schema:
            format: int64
            type:
              - integer
              - 'null'
        - description: ''
          in: query
          name: model
          required: false
          schema:
            type:
              - string
              - 'null'
        - description: ''
          in: query
          name: operation
          required: false
          schema:
            type:
              - string
              - 'null'
        - description: 1-based. Zero and absent both mean the first page.
          in: query
          name: page
          required: false
          schema:
            description: 1-based. Zero and absent both mean the first page.
            format: uint64
            minimum: 0
            type:
              - integer
              - 'null'
        - description: Clamped to 1..=500; absent means 50.
          in: query
          name: pageSize
          required: false
          schema:
            description: Clamped to 1..=500; absent means 50.
            format: uint64
            minimum: 0
            type:
              - integer
              - 'null'
        - description: Records whose structured upstream usage matches this provider.
          in: query
          name: providerId
          required: false
          schema:
            description: Records whose structured upstream usage matches this provider.
            type:
              - string
              - 'null'
        - description: ''
          in: query
          name: requestId
          required: false
          schema:
            type:
              - string
              - 'null'
        - description: ''
          in: query
          name: toMs
          required: false
          schema:
            format: int64
            type:
              - integer
              - 'null'
        - description: ''
          in: query
          name: userId
          required: false
          schema:
            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_UsageRecordPage'
          description: Success
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Output_Envelope'
          description: Gateway error
      security:
        - consoleSession: []
        - bearer: []
        - anthropicKey: []
        - googleKey: []
components:
  schemas:
    Output_UsageRecordPage:
      description: >-
        One exact database page; provider and credential filters are SQL
        predicates.
      properties:
        items:
          items:
            $ref: '#/components/schemas/Output_UsageRecordDto'
          type: array
        limit:
          format: uint64
          minimum: 0
          type: integer
        offset:
          format: uint64
          minimum: 0
          type: integer
        total:
          format: uint64
          minimum: 0
          type: integer
        truncated:
          type: boolean
      required:
        - items
        - total
        - offset
        - limit
        - truncated
      type: object
    Output_Envelope:
      properties:
        error:
          $ref: '#/components/schemas/Output_EnvelopeBody'
      required:
        - error
      type: object
    Output_UsageRecordDto:
      description: One persisted physical upstream call.
      properties:
        actualServiceTier:
          type:
            - string
            - 'null'
        apiKeyId:
          type:
            - string
            - 'null'
        completeness:
          description: '`complete`, `partial` or `unknown`.'
          type:
            - string
            - 'null'
        cost:
          description: The settled USD charge, read from its dedicated column.
          type:
            - string
            - 'null'
        currency:
          type:
            - string
            - 'null'
        durationMs:
          format: int64
          type:
            - integer
            - 'null'
        endedAtMs:
          format: int64
          type:
            - integer
            - 'null'
        exchanges:
          description: >-
            Detail of this physical call, retaining the existing exchange DTO
            shape.
          items:
            $ref: '#/components/schemas/Output_UsageExchangeDto'
          type: array
        metrics:
          description: >-
            Dynamic dimensions and nested protocol-specific detail; fixed fields
            are above.
        model:
          description: The upstream model the call was routed to.
          type: string
        operation:
          type: string
        quantities:
          additionalProperties:
            type: string
          description: >-
            Reported media/tool quantities, as exact decimal strings. Missing is
            unknown.
          type: object
        requestId:
          description: >-
            Physical upstream call ID. A corresponding capture log need not
            exist.
          type: string
        responseModel:
          description: >-
            The model the upstream response named, which may differ from
            `model`.
          type:
            - string
            - 'null'
        startedAtMs:
          format: int64
          type: integer
        state:
          description: 'The settlement state core recorded: `settled`, `failed`, … .'
          type:
            - string
            - 'null'
        tokens:
          $ref: '#/components/schemas/Output_UsageTokensDto'
        ttftMs:
          format: int64
          type:
            - integer
            - 'null'
        userId:
          type:
            - string
            - 'null'
      required:
        - requestId
        - userId
        - apiKeyId
        - model
        - responseModel
        - operation
        - state
        - completeness
        - actualServiceTier
        - tokens
        - quantities
        - cost
        - currency
        - exchanges
        - metrics
        - startedAtMs
        - endedAtMs
        - durationMs
        - ttftMs
      type: object
    Output_EnvelopeBody:
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message
      type: object
    Output_UsageExchangeDto:
      description: |-
        One upstream attempt inside a request: which provider and credential
        served it, and what it cost on its own.
      properties:
        actualServiceTier:
          type:
            - string
            - 'null'
        attemptId:
          type:
            - string
            - 'null'
        attemptOrdinal:
          format: int64
          type:
            - integer
            - 'null'
        captureId:
          type:
            - string
            - 'null'
        completeness:
          type:
            - string
            - 'null'
        cost:
          type:
            - string
            - 'null'
        credentialId:
          type:
            - string
            - 'null'
        currency:
          type:
            - string
            - 'null'
        metrics:
          description: Dynamic dimensions and nested protocol-specific usage detail.
        model:
          description: The upstream model name, which need not be the requested one.
          type:
            - string
            - 'null'
        providerId:
          type:
            - string
            - 'null'
        quantities:
          additionalProperties:
            type: string
          description: >-
            Reported media/tool quantities, as exact decimal strings. Missing is
            unknown.
          type: object
        responseModel:
          description: >-
            The model the upstream response named, which may differ from
            `model`.
          type:
            - string
            - 'null'
        tokens:
          $ref: '#/components/schemas/Output_UsageTokensDto'
      required:
        - captureId
        - completeness
        - actualServiceTier
        - metrics
        - attemptId
        - attemptOrdinal
        - providerId
        - credentialId
        - model
        - responseModel
        - tokens
        - quantities
        - cost
        - currency
      type: object
    Output_UsageTokensDto:
      description: Token counts exactly as the upstream reported them.
      properties:
        cacheCreation:
          items:
            $ref: '#/components/schemas/Output_CacheCreationDto'
          type: array
        cachedInputTokens:
          format: uint64
          minimum: 0
          type:
            - integer
            - 'null'
        inputTokens:
          description: Ordinary input, excluding cache reads and cache writes.
          format: uint64
          minimum: 0
          type:
            - integer
            - 'null'
        outputTokens:
          description: Total output, reasoning included.
          format: uint64
          minimum: 0
          type:
            - integer
            - 'null'
        reasoningTokens:
          description: A subset of `output_tokens`, never additive with it.
          format: uint64
          minimum: 0
          type:
            - integer
            - 'null'
      required:
        - inputTokens
        - outputTokens
        - cachedInputTokens
        - cacheCreation
        - reasoningTokens
      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

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


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