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

# List metered API usage



## OpenAPI

````yaml /openapi.json get /api/v1/billing/usage
openapi: 3.1.0
info:
  title: Esheria Regulatory API
  version: 1.0.0
  description: >-
    Citation-backed regulatory pack API for pack discovery, obligations,
    applicability checks, version history, diffs, change events, evidence
    requirements, filing rules, penalty facts, legal review audit metadata,
    graph queries, and claim verification.
servers:
  - url: https://api.esheria.ai
    description: Production API
  - url: http://127.0.0.1:8080
    description: Local development runtime
security: []
paths:
  /api/v1/billing/usage:
    get:
      tags:
        - Billing
      summary: List metered API usage
      operationId: billing_usage_api_v1_billing_usage_get
      parameters:
        - name: token_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Token Id
        - name: endpoint_family
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Endpoint Family
        - name: pack_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Pack Id
        - name: date_from
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Date From
        - name: date_to
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Date To
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 500
            minimum: 1
            title: Limit
            default: 100
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            title: Offset
            default: 0
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                status: error
                errors:
                  - code: unauthorized
                    message: Invalid API key
                trace_id: trace-123
        '402':
          description: Credits exhausted
          content:
            application/json:
              example:
                status: error
                errors:
                  - code: credits_exhausted
                    message: API credits exhausted
                trace_id: trace-123
        '409':
          description: Conflict
          content:
            application/json:
              example:
                status: error
                errors:
                  - code: duplicate_token_name
                    message: An active data token already uses that name.
                trace_id: trace-123
        '422':
          description: Validation error
          content:
            application/json:
              example:
                status: error
                errors:
                  - code: validation_error
                    message: Invalid payload
                    field: body.name
                trace_id: trace-123
        '503':
          description: Billing or dependency unavailable
          content:
            application/json:
              example:
                status: error
                errors:
                  - code: billing_unavailable
                    message: Billing ledger is unavailable
                trace_id: trace-123
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Client API key issued by Esheria.
      x-default: YOUR_ESHERIA_API_KEY

````