---
title: "Series"
method: GET
path: "/api/v1/usage/series"
tags: ["usage"]
---

# Series

`GET /api/v1/usage/series`

## Request

- Base URL: `https://api.capy.ai`
- URL: `https://api.capy.ai/api/v1/usage/series`
- Auth: HTTP bearer

## 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` 'day' | 'hour': Bucket width, in UTC. Defaults to `day`.
- `groupBy` union: Splits each bucket by `user`, `thread`, or billing `item`; repeat it to combine them (`groupBy=user&groupBy=item`). Absent, each bucket has one total.
  - 'user' | 'thread' | 'item'
  - string[]
- `userIds` union: Only usage by these user or service-user ids; repeat to pass several.
  - string
  - string[]
- `projectIds` union: Only usage in these projects; repeat to pass several. Intersected with the key's project access.
  - string
  - string[]
- `threadIds` union: Only usage in these threads and their subagents; repeat to pass several. Threads this key cannot read match nothing.
  - string
  - string[]
- `models` union: Only model usage served by these model ids; repeat to pass several.
  - string
  - string[]
- `limit` string: Rows per page, 1 to 1000. Defaults to 100.
- `cursor` string: Opaque page token: pass the previous page's `cursor` back with the same window, granularity, grouping, and filters.

## Response `200`

UsageSeriesPage

- UsageSeriesPageEncoded
  - `currency` 'USD', required: The currency of every dollar amount in the response.
  - `from` string, required
  - `to` string, required
  - `granularity` 'day' | 'hour', required
  - `groupBy` string[], required
  - `items` UsageSeriesItemEncoded[], required: 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`.
    - `start` string, required
    - `end` string, required
    - `dimensions` UsageDimensionsEncoded, required
      - `userId` string, nullable: With `groupBy=user`: the acting user or service-user id; null for spend with no acting user.
      - `threadId` string, nullable: With `groupBy=thread`: the thread id (subagent spend counts toward its thread), `private` for threads this key cannot read, or null for spend outside any thread.
      - `itemType` 'llm' | 'review' | 'machine' | 'image': With `groupBy=item`: `llm` for model usage, `review` for code review, `machine` for machine time, `image` for image generation.
      - `itemId` string: With `groupBy=item`: the model id for `llm`, `review` for `review`, the machine size for `machine`, and the generation endpoint for `image`.
      - `model` string, nullable: With `groupBy=item`: the model id for `llm` items; null for every other item type.
      - `label` string: With `groupBy=item`: the item's display name.
    - `llmDollars` union, required
      - number
      - 'Infinity' | '-Infinity' | 'NaN'
    - `imageDollars` union, required
      - number
      - 'Infinity' | '-Infinity' | 'NaN'
    - `vmDollars` union, required
      - number
      - 'Infinity' | '-Infinity' | 'NaN'
    - `standaloneTokenFeeDollars` union, required
      - number
      - 'Infinity' | '-Infinity' | 'NaN'
    - `billedDollars` union, required
      - number
      - 'Infinity' | '-Infinity' | 'NaN'
    - `referenceDollars` UsageReferenceDollarsEncoded, required
      - `connectedSubscription` union, required
        - number
        - 'Infinity' | '-Infinity' | 'NaN'
      - `byok` union, required
        - number
        - 'Infinity' | '-Infinity' | 'NaN'
    - `tokens` UsageTokenTotalsEncoded, required
      - `inputTokens` union, required
        - number
        - 'Infinity' | '-Infinity' | 'NaN'
      - `outputTokens` union, required
        - number
        - 'Infinity' | '-Infinity' | 'NaN'
      - `cacheReadTokens` union, required
        - number
        - 'Infinity' | '-Infinity' | 'NaN'
      - `cacheWriteTokens` union, required
        - number
        - 'Infinity' | '-Infinity' | 'NaN'
  - `cursor` string, nullable, required: Opaque page token: pass the previous page's `cursor` back with the same window, granularity, grouping, and filters.

## Other responses

- `400`: capy/InvalidRequest
- `401`: capy/Unauthorized
- `403`: capy/Forbidden
- `429`: capy/RateLimited
- `503`: capy/UsageUnavailable

## Changes

- **2026-10-29** `6077fbba29f8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/capy/apis/capy-api/changes/api/v1/usage/series/get.md)

---

[API](https://skmtc.dev/capy/apis/capy-api.md) - [All operations](https://skmtc.dev/capy/apis/capy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/capy/apis/capy-api/revisions/4663f7dc4e39?raw)