---
title: "Per-document API usage"
method: GET
path: "/v1/usage/documents/{id}"
tags: ["Usage"]
---

# Per-document API usage

`GET /v1/usage/documents/{id}`

## Request

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

Returns per-document API usage entries and totals. 404 if no usage
records exist for the document.

For organizations without the "Cost control endpoints" approval,
`model` and all cost fields (`cost_estimate_usd` on both `totals` and
each `entries[]` row) are redacted (omitted), and the response
carries `"cost_fields": "redacted"`. Approved organizations see these
fields unredacted and no `cost_fields` marker.

## Path parameters

- `id` string, uuid, required

## Response `200`

Per-document usage breakdown.

- DocumentUsageResponse
  - `document_id` string, uuid, 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).
    - `cost_estimate_usd` number, float: Omitted for organizations without the "Cost control endpoints" approval (see `cost_fields` on the parent response).
    - `calls` integer, required
  - `entries` object[], required
    - `id` string, required
    - `operation_type` string, required
    - `model` string: Omitted for organizations without the "Cost control endpoints" approval.
    - `input_tokens` integer, required
    - `output_tokens` integer, required
    - `cache_read_tokens` integer, nullable, 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).
    - `cost_estimate_usd` number, float: Omitted for organizations without the "Cost control endpoints" approval.
    - `created_at` string, date-time, required
  - `cost_fields` 'redacted': Present and set to `"redacted"` only for organizations without the "Cost control endpoints" approval — signals that `model` and all `cost_estimate_usd` fields have been omitted. Absent for approved organizations.
  - `links` object, required
    - `self` string
    - `document` string

## Other responses

- `401`: Missing or invalid API key.
- `404`: The requested resource was not found.
- `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)