Series

GET
/api/v1/usage/series

Authorization

bearerAuth
headerAuthorizationBearer <token>

An API key created in Capy under Settings → API.

Query parameters

from?string

Inclusive window start. Defaults to the start of the current UTC calendar month. The window reaches back at most a year before to, or 31 days for hour.

to?string

Exclusive window end. Defaults to now.

granularity?string

Bucket width, in UTC. Defaults to day.

One of"day""hour"
groupBy?|array<>

Splits each bucket by user, thread, or billing item; repeat it to combine them (groupBy=user&groupBy=item). Absent, each bucket has one total.

userIds?|array<string>

Only usage by these user or service-user ids; repeat to pass several.

projectIds?|array<string>

Only usage in these projects; repeat to pass several. Intersected with the key's project access.

threadIds?|array<string>

Only usage in these threads and their subagents; repeat to pass several. Threads this key cannot read match nothing.

models?|array<string>

Only model usage served by these model ids; repeat to pass several.

limit?string

Rows per page, 1 to 1000. Defaults to 100.

Match^[+-]?\d*\.?\d+(?:[Ee][+-]?\d+)?$
cursor?string

Opaque page token: pass the previous page's cursor back with the same window, granularity, grouping, and filters.

Match^\d{1,15}:

Response body

UsageSeriesPage

application/json
  1. response
currency*"USD"

The currency of every dollar amount in the response.

One of"USD"
from*string
to*string
granularity*string
One of"day""hour"
groupBy*array<>
items*array<>

Rows ordered by bucket start, then dimensions. A row is omitted when every money and token field is zero. Recent buckets can still change while usage settles and the analytics copy syncs, so re-read them and upsert by start and dimensions.

cursor*|

Token for the next page; null on the last page.

curl -X GET 'https://api.capy.ai/api/v1/usage/series'
{  "currency": "USD",  "from": "string",  "to": "string",  "granularity": "day",  "groupBy": [    "user"  ],  "items": [    {      "start": "string",      "end": "string",      "dimensions": {        "userId": "string",        "threadId": "string",        "itemType": "llm",        "itemId": "string",        "model": "string",        "label": "string"      },      "llmDollars": 0,      "imageDollars": 0,      "vmDollars": 0,      "standaloneTokenFeeDollars": 0,      "billedDollars": 0,      "referenceDollars": {        "connectedSubscription": 0,        "byok": 0      },      "tokens": {        "inputTokens": 0,        "outputTokens": 0,        "cacheReadTokens": 0,        "cacheWriteTokens": 0      }    }  ],  "cursor": "string"}
Open in Capy