Skip to main content
GET
/
api
/
v1
/
tokens
Token Analytics
curl --request GET \
  --url https://api.example.com/api/v1/tokens
{
  "summary": {
    "total_tokens": {
      "value": 123,
      "trend_pct": 123,
      "sub_values": {
        "input": 123,
        "output": 123
      }
    },
    "input_tokens": 123,
    "output_tokens": 123
  },
  "hourly": [
    {
      "hour": "<string>",
      "input_tokens": 123,
      "output_tokens": 123
    }
  ],
  "daily": [
    {
      "date": "<string>",
      "input_tokens": 123,
      "output_tokens": 123
    }
  ]
}

​
Overview

The tokens endpoint provides granular token usage data, including summary statistics and separate hourly/daily timeseries. This endpoint returns both aggregation types simultaneously, allowing clients to choose the appropriate granularity for visualization.

​
Authentication

Requires session authentication (cookie) or API key via X-API-Key header.

​
Query Parameters

​
range
string
default:"24h"
Time range for analytics. Valid values: 1h, 6h, 24h, 7d, 30d
​
agent_name
string
Filter analytics to a specific agent. If omitted, returns data for all agents.

​
Response Schema

​
summary
object
Token usage summary for the selected time range
​
hourly
array
Token usage aggregated by hour
​
daily
array
Token usage aggregated by day

​
Example Request

cURL
curl -X GET "https://api.manifest.build/api/v1/tokens?range=7d&agent_name=research-agent" \
  -H "X-API-Key: your-api-key"

​
Example Response

{
  "summary": {
    "total_tokens": {
      "value": 1458920,
      "trend_pct": 15.3,
      "sub_values": {
        "input": 985000,
        "output": 473920
      }
    },
    "input_tokens": 985000,
    "output_tokens": 473920
  },
  "hourly": [
    {
      "hour": "2026-02-26 00:00:00",
      "input_tokens": 12500,
      "output_tokens": 5800
    },
    {
      "hour": "2026-02-26 01:00:00",
      "input_tokens": 8900,
      "output_tokens": 3200
    },
    {
      "hour": "2026-02-26 02:00:00",
      "input_tokens": 15200,
      "output_tokens": 7100
    }
  ],
  "daily": [
    {
      "date": "2026-02-26",
      "input_tokens": 145000,
      "output_tokens": 68000
    },
    {
      "date": "2026-02-27",
      "input_tokens": 132000,
      "output_tokens": 61500
    },
    {
      "date": "2026-02-28",
      "input_tokens": 158000,
      "output_tokens": 72800
    },
    {
      "date": "2026-03-01",
      "input_tokens": 168000,
      "output_tokens": 79200
    },
    {
      "date": "2026-03-02",
      "input_tokens": 142000,
      "output_tokens": 66300
    },
    {
      "date": "2026-03-03",
      "input_tokens": 125000,
      "output_tokens": 58900
    },
    {
      "date": "2026-03-04",
      "input_tokens": 115000,
      "output_tokens": 67220
    }
  ]
}

​
Notes

  • Both aggregations returned: Unlike /overview, this endpoint returns both hourly and daily arrays in every response, regardless of the range parameter. Clients can choose which to display.
  • Trend calculation: Compares current period vs. previous period of equal length. For 7d range, compares last 7 days vs. previous 7 days.
  • Caching: Responses are cached for 5 minutes (see DASHBOARD_CACHE_TTL_MS).
  • Multi-tenancy: Data is automatically filtered by authenticated user.
  • Token counting: Input tokens = prompt/context tokens. Output tokens = completion/generated tokens. Cache tokens are tracked separately and not included in these totals.
  • Empty buckets: Time periods with no activity return input_tokens: 0 and output_tokens: 0.

Build docs developers (and LLMs) love

Get started for freeTalk to us