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

# Usage

> Returns account credit consumption, active scoped grants, and recent
upstream usage events. This endpoint bypasses the quota gate so a
depleted account can still inspect its balance.


<div className="endpoint-signature"><span className="endpoint-method endpoint-method-get">GET</span><code>/v1/usage</code></div>


## OpenAPI

````yaml /openapi/usage.yaml get /v1/usage
openapi: 3.1.0
info:
  title: Tokenless Cost and Usage API
  version: 1.0.0
  description: |
    Account credit, routed-request cost, usage history, and session aggregate
    endpoints. Monetary amounts are integer USD nanos:
    1,000,000,000 nanos equals US $1.00.
servers:
  - url: https://api.usetokenless.com
security:
  - bearerAuth: []
paths:
  /v1/usage:
    get:
      summary: Usage
      description: |
        Returns account credit consumption, active scoped grants, and recent
        upstream usage events. This endpoint bypasses the quota gate so a
        depleted account can still inspect its balance.
      operationId: getUsage
      parameters:
        - $ref: '#/components/parameters/RecentLimit'
      responses:
        '200':
          description: Account balance and recent events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  parameters:
    RecentLimit:
      name: limit
      in: query
      description: Number of recent upstream events. Defaults to 20; maximum 200.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 20
  schemas:
    UsageSummary:
      type: object
      required:
        - limit_nanos
        - used_nanos
        - grants
        - recent_events
      properties:
        limit_nanos:
          type: integer
          format: int64
          description: Account credit ceiling in USD nanos.
        used_nanos:
          type: integer
          format: int64
          description: Credit consumed in USD nanos.
        grants:
          type: array
          items:
            $ref: '#/components/schemas/Grant'
        recent_events:
          type: array
          items:
            $ref: '#/components/schemas/UsageEvent'
    Grant:
      type: object
      required:
        - id
        - amount_nanos
        - remaining_nanos
        - scope_cost_type
        - source
        - created_at
      properties:
        id:
          type: string
        amount_nanos:
          type: integer
          format: int64
        remaining_nanos:
          type: integer
          format: int64
        scope_cost_type:
          type: string
        scope_routing_modes:
          type: array
          items:
            type: string
        scope_models:
          type: array
          items:
            type: string
        scope_providers:
          type: array
          items:
            type: string
        expires_at:
          type: string
          format: date-time
        source:
          type: string
        created_at:
          type: string
          format: date-time
    UsageEvent:
      type: object
      required:
        - request_id
        - model_id
        - provider_id
        - committed
        - estimated
        - input_tokens
        - cached_input_tokens
        - cache_creation_input_tokens
        - output_tokens
        - cost_nanos
        - created_at
      properties:
        request_id:
          type: string
        model_id:
          type: string
        provider_id:
          type: string
        committed:
          type: boolean
        estimated:
          type: boolean
        input_tokens:
          type: integer
          format: int64
        cached_input_tokens:
          type: integer
          format: int64
        cache_creation_input_tokens:
          type: integer
          format: int64
        output_tokens:
          type: integer
          format: int64
        cost_nanos:
          type: integer
          format: int64
        created_at:
          type: string
          format: date-time
  responses:
    Unauthorized:
      description: Missing or invalid authentication.
    ServerError:
      description: The service could not load the requested usage data.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Tokenless API key, Clerk JWT, or tkl CLI session

````