---
title: "Aggregate API usage stats"
method: GET
path: "/v1/usage"
tags: ["Usage"]
---

# Aggregate API usage stats

`GET /v1/usage`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/usage`
- Auth: HTTP bearer

Returns token and call counts aggregated by `operation_type` and
`model` over the requested date range. Default range is the last 30
days.

For organizations without the "Cost control endpoints" approval,
`breakdown[].model` is redacted (omitted) and the response carries
`"cost_fields": "redacted"`. Approved organizations see the field
unredacted and no `cost_fields` marker. This applies uniformly —
every tenant, not just consumers of the per-document route.

## Query parameters

- `from` string, date-time
- `to` string, date-time

## Response `200`

Aggregated usage stats.

- UsageResponse
  - `period` object, required
    - `from` string, date-time, required
    - `to` string, date-time, required
  - `totals` object, required
    - `input_tokens` integer, required: Uncached input tokens (cached tokens are reported separately).
    - `output_tokens` integer, required
    - `cache_read_tokens` integer, required: Tokens served from the provider's prompt cache.
    - `cache_creation_tokens` integer, required: Tokens written to the provider's prompt cache (Anthropic only; 0 for other providers).
    - `calls` integer, required
  - `breakdown` object[], required
    - `operation_type` string, required
    - `model` string: Omitted for organizations without the "Cost control endpoints" approval (see `cost_fields` on the parent response).
    - `input_tokens` integer, required: Uncached input tokens (cached tokens are reported separately).
    - `output_tokens` integer, required
    - `cache_read_tokens` integer, required: Tokens served from the provider's prompt cache.
    - `cache_creation_tokens` integer, required: Tokens written to the provider's prompt cache (Anthropic only; 0 for other providers).
    - `calls` integer, required
  - `cost_fields` 'redacted': Present and set to `"redacted"` only for organizations without the "Cost control endpoints" approval — signals that `breakdown[].model` has been omitted. Absent for approved organizations.
  - `links` object, required
    - `self` string

## Other responses

- `401`: Missing or invalid API key.
- `429`: Daily rate limit exceeded.

---

[API](https://skmtc.dev/talonic/apis/talonic-api.md) · [All operations](https://skmtc.dev/talonic/apis/talonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talonic/apis/talonic-api/revisions/678fe5f8c9c3?raw)