---
title: "Query token usage"
method: GET
path: "/api/tokens"
tags: ["Tokens"]
---

# Query token usage

`GET /api/tokens`

## Query parameters

- `action` 'list' | 'stats' | 'agent-costs' | 'export' | 'trends'
- `timeframe` 'hour' | 'day' | 'week' | 'month' | 'all'
- `format` 'json' | 'csv'

## Response `200`

Token usage data. Shape varies by action.

- union
  - object
    - `usage` TokenUsageRecord[]
      - `id` string
      - `model` string
      - `sessionId` string
      - `timestamp` integer
      - `inputTokens` integer
      - `outputTokens` integer
      - `totalTokens` integer
      - `cost` number
      - `operation` string
      - `duration` number
    - `total` integer
    - `timeframe` string
  - object
    - `summary` TokenStats
      - `totalTokens` integer
      - `totalCost` number
      - `requestCount` integer
      - `avgTokensPerRequest` integer
      - `avgCostPerRequest` number
    - `models` object
    - `sessions` object
    - `agents` object
    - `timeframe` string
    - `recordCount` integer
  - object
    - `trends` object[]
      - `timestamp` string
      - `tokens` integer
      - `cost` number
      - `requests` integer
    - `timeframe` string

## Other responses

- `400` — Invalid request
- `401` — Authentication required

---

[API](https://skmtc.net/builderz-labs/apis/mission-control-api.md) · [All operations](https://skmtc.net/builderz-labs/apis/mission-control-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/builderz-labs/mission-control-api/revisions/b920835b2793/schema)