# Series (https://docs.capy.ai/api-reference/usage/series)

`GET https://api.capy.ai/api/v1/usage/series`

## Authorization

Send an API key as a bearer token: `Authorization: Bearer $CAPY_API_KEY`. See https://docs.capy.ai/api-reference/authentication.md.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `from` | query | string | no |  |
| `to` | query | string | no |  |
| `granularity` | query | `day` \| `hour` | no |  |
| `groupBy` | query | `user` \| `thread` \| `item` \| `user` \| `thread` \| `item`[] | no |  |
| `userIds` | query | string \| string[] | no |  |
| `projectIds` | query | string \| string[] | no |  |
| `threadIds` | query | string \| string[] | no |  |
| `models` | query | string \| string[] | no |  |
| `limit` | query | string | no |  |
| `cursor` | query | string | no |  |

## Responses

- `200` UsageSeriesPage: `UsageSeriesPageEncoded`
- `400` capy/InvalidRequest: `capy_InvalidRequestEncoded`
- `401` capy/Unauthorized: `capy_UnauthorizedEncoded`
- `403` capy/Forbidden: `capy_ForbiddenEncoded`
- `429` capy/RateLimited: `capy_RateLimitedEncoded`
- `503` capy/UsageUnavailable: `capy_UsageUnavailableEncoded`

## Example

```bash
curl -X GET "https://api.capy.ai/api/v1/usage/series" \
  -H "Authorization: Bearer $CAPY_API_KEY"
```

## Referenced schemas

```json
{
  "UsageSeriesPageEncoded": {
    "type": "object",
    "properties": {
      "currency": {
        "type": "string",
        "enum": [
          "USD"
        ],
        "description": "The currency of every dollar amount in the response."
      },
      "from": {
        "type": "string"
      },
      "to": {
        "type": "string"
      },
      "granularity": {
        "type": "string",
        "enum": [
          "day",
          "hour"
        ]
      },
      "groupBy": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "user",
            "thread",
            "item"
          ]
        }
      },
      "items": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/UsageSeriesItemEncoded"
        },
        "description": "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": {
        "anyOf": [
          {
            "type": "string",
            "pattern": "^\\d{1,15}:",
            "description": "Opaque page token: pass the previous page's `cursor` back with the same window, granularity, grouping, and filters."
          },
          {
            "type": "null"
          }
        ],
        "description": "Token for the next page; null on the last page."
      }
    },
    "required": [
      "currency",
      "from",
      "to",
      "granularity",
      "groupBy",
      "items",
      "cursor"
    ],
    "additionalProperties": false
  },
  "UsageSeriesItemEncoded": {
    "type": "object",
    "properties": {
      "start": {
        "type": "string"
      },
      "end": {
        "type": "string"
      },
      "dimensions": {
        "$ref": "#/components/schemas/UsageDimensionsEncoded"
      },
      "llmDollars": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string",
            "enum": [
              "Infinity",
              "-Infinity",
              "NaN"
            ]
          }
        ]
      },
      "imageDollars": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string",
            "enum": [
              "Infinity",
              "-Infinity",
              "NaN"
            ]
          }
        ]
      },
      "vmDollars": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string",
            "enum": [
              "Infinity",
              "-Infinity",
              "NaN"
            ]
          }
        ]
      },
      "standaloneTokenFeeDollars": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string",
            "enum": [
              "Infinity",
              "-Infinity",
              "NaN"
            ]
          }
        ]
      },
      "billedDollars": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string",
            "enum": [
              "Infinity",
              "-Infinity",
              "NaN"
            ]
          }
        ]
      },
      "referenceDollars": {
        "$ref": "#/components/schemas/UsageReferenceDollarsEncoded"
      },
      "tokens": {
        "$ref": "#/components/schemas/UsageTokenTotalsEncoded"
      }
    },
    "required": [
      "start",
      "end",
      "dimensions",
      "llmDollars",
      "imageDollars",
      "vmDollars",
      "standaloneTokenFeeDollars",
      "billedDollars",
      "referenceDollars",
      "tokens"
    ],
    "additionalProperties": false
  },
  "UsageDimensionsEncoded": {
    "type": "object",
    "properties": {
      "userId": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "With `groupBy=user`: the acting user or service-user id; null for spend with no acting user."
      },
      "threadId": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "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": {
        "type": "string",
        "enum": [
          "llm",
          "review",
          "machine",
          "image"
        ],
        "description": "With `groupBy=item`: `llm` for model usage, `review` for code review, `machine` for machine time, `image` for image generation."
      },
      "itemId": {
        "type": "string",
        "description": "With `groupBy=item`: the model id for `llm`, `review` for `review`, the machine size for `machine`, and the generation endpoint for `image`."
      },
      "model": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "With `groupBy=item`: the model id for `llm` items; null for every other item type."
      },
      "label": {
        "type": "string",
        "description": "With `groupBy=item`: the item's display name."
      }
    },
    "additionalProperties": false
  },
  "UsageReferenceDollarsEncoded": {
    "type": "object",
    "properties": {
      "connectedSubscription": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string",
            "enum": [
              "Infinity",
              "-Infinity",
              "NaN"
            ]
          }
        ]
      },
      "byok": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string",
            "enum": [
              "Infinity",
              "-Infinity",
              "NaN"
            ]
          }
        ]
      }
    },
    "required": [
      "connectedSubscription",
      "byok"
    ],
    "additionalProperties": false
  },
  "UsageTokenTotalsEncoded": {
    "type": "object",
    "properties": {
      "inputTokens": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string",
            "enum": [
              "Infinity",
              "-Infinity",
              "NaN"
            ]
          }
        ]
      },
      "outputTokens": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string",
            "enum": [
              "Infinity",
              "-Infinity",
              "NaN"
            ]
          }
        ]
      },
      "cacheReadTokens": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string",
            "enum": [
              "Infinity",
              "-Infinity",
              "NaN"
            ]
          }
        ]
      },
      "cacheWriteTokens": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string",
            "enum": [
              "Infinity",
              "-Infinity",
              "NaN"
            ]
          }
        ]
      }
    },
    "required": [
      "inputTokens",
      "outputTokens",
      "cacheReadTokens",
      "cacheWriteTokens"
    ],
    "additionalProperties": false
  },
  "capy_InvalidRequestEncoded": {
    "type": "object",
    "properties": {
      "_tag": {
        "type": "string",
        "enum": [
          "capy/InvalidRequest"
        ]
      },
      "message": {
        "type": "string"
      }
    },
    "required": [
      "_tag",
      "message"
    ],
    "additionalProperties": false
  },
  "capy_UnauthorizedEncoded": {
    "type": "object",
    "properties": {
      "_tag": {
        "type": "string",
        "enum": [
          "capy/Unauthorized"
        ]
      }
    },
    "required": [
      "_tag"
    ],
    "additionalProperties": false
  },
  "capy_ForbiddenEncoded": {
    "type": "object",
    "properties": {
      "_tag": {
        "type": "string",
        "enum": [
          "capy/Forbidden"
        ]
      }
    },
    "required": [
      "_tag"
    ],
    "additionalProperties": false
  },
  "capy_RateLimitedEncoded": {
    "type": "object",
    "properties": {
      "_tag": {
        "type": "string",
        "enum": [
          "capy/RateLimited"
        ]
      },
      "retryAfterSeconds": {
        "type": "integer"
      }
    },
    "required": [
      "_tag",
      "retryAfterSeconds"
    ],
    "additionalProperties": false
  },
  "capy_UsageUnavailableEncoded": {
    "type": "object",
    "properties": {
      "_tag": {
        "type": "string",
        "enum": [
          "capy/UsageUnavailable"
        ]
      }
    },
    "required": [
      "_tag"
    ],
    "additionalProperties": false
  }
}
```

Full document: https://docs.capy.ai/openapi.json