Sign in

v1

latestOpenAPI 3.1.0MIT2026-07-262861121.0 KB

Retrieve aggregate spend, request, and token usage for the authenticated API key, grouped by UTC day, model, or both.

get/v1/usage

Query parameters

fromstring date
Example:2026-05-01

UTC start date in YYYY-MM-DD format. Must be provided together with to.

tostring date
Example:2026-05-31

UTC end date in YYYY-MM-DD format, inclusive. Must be on or after from and cannot be in the future.

group_by'day' | 'model' | 'day,model' | 'model,day'
Example:day,model

Controls which aggregate arrays are returned. model,day is accepted as an alias for day,model.

scope'current_key' | 'api_key'

Usage scope. current_key and api_key both return usage for the authenticated API key.

api_key_idinteger
Example:123

Optional current API key ID. Requests for another API key are rejected.

Response

Aggregate usage for the authenticated API key

object'usage' required

Always usage.

scope'current_key' | 'api_key' required

Echoes the requested usage scope.

fromstring date required

UTC start date.

tostring date required

UTC end date, inclusive.

timezone'UTC' required

Always UTC.

groupBy'day' | 'model' | 'day,model' required

The effective grouping mode.

asOfstring date-time required

Timestamp when the aggregate response was generated. Cached responses can be up to 60 seconds old.

Example response

{
  "apiKey": {
    "id": 123
  },
  "from": "2026-05-01",
  "to": "2026-05-31",
  "groupBy": "day,model",
  "asOf": "2026-05-31T12:00:00.000Z",
  "source": {
    "rollupDays": [
      "2026-05-01"
    ],
    "liveDays": [
      "2026-05-31"
    ],
    "missingRollupDays": []
  },
  "totals": {
    "date": "2026-05-01",
    "model": "GPT-4.1 mini",
    "requests": 1284,
    "costUsd": 42.18,
    "refundedUsd": 1.25,
    "netCostUsd": 40.93,
    "inputTokens": 1234567,
    "outputTokens": 456789,
    "reasoningTokens": 12000,
    "totalTokens": 1691356
  },
  "byDay": [
    {
      "date": "2026-05-01",
      "model": "GPT-4.1 mini",
      "requests": 1284,
      "costUsd": 42.18,
      "refundedUsd": 1.25,
      "netCostUsd": 40.93,
      "inputTokens": 1234567,
      "outputTokens": 456789,
      "reasoningTokens": 12000,
      "totalTokens": 1691356
    }
  ],
  "byModel": [
    {
      "date": "2026-05-01",
      "model": "GPT-4.1 mini",
      "requests": 1284,
      "costUsd": 42.18,
      "refundedUsd": 1.25,
      "netCostUsd": 40.93,
      "inputTokens": 1234567,
      "outputTokens": 456789,
      "reasoningTokens": 12000,
      "totalTokens": 1691356
    }
  ],
  "byDayModel": [
    {
      "date": "2026-05-01",
      "model": "GPT-4.1 mini",
      "requests": 1284,
      "costUsd": 42.18,
      "refundedUsd": 1.25,
      "netCostUsd": 40.93,
      "inputTokens": 1234567,
      "outputTokens": 456789,
      "reasoningTokens": 12000,
      "totalTokens": 1691356
    }
  ]
}