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

# Per-run API usage

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

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/usage/runs/{id}`
- Auth: `ApiKeyAuth` (a scheme the document does not define)

Returns AI usage for one `/v1/run` request: totals, a breakdown by
`operation_type` × `model`, and a per-document rollup. `id` is the
`/v1/run` request id (the `run_id` from `POST /v1/run` / `GET
/v1/run/:id`), not a pipeline id.

`scope` is a fixed code (`run_attributed_calls`) and `scope_note` is
the human-readable statement of what this covers.

A run that is still ingesting, or that failed before a pipeline was
created (`pipeline_id IS NULL`), returns `200` with zero totals and
`scope_note` explaining why — never `404` — since pollers hit this
window constantly. A legacy run request that predates per-request
document tracking (no `documents[]` echo) returns the same zero-total
shape with its own `scope_note`, even when `pipeline_id` is set.

Attribution is the intersection of: calls stamped with the run's
pipeline, limited to the run's own `documents[]` echo, and inside the
run's active time window (open-ended while the run is live; bounded
at `updated_at` + a short margin once terminal, so completion-adjacent
calls are still captured without a later rerun or append on the same
shared pipeline bleeding in). This is documented as approximate under
shared-pipeline concurrency (append mode, or several runs targeting
the same pipeline). A document skipped by dedup or extraction-reuse
legitimately shows zeros for that document.

Same gating as the pipeline route: requires the org's "Cost control
endpoints" approval (`404` otherwise) AND an API key carrying the
`usage` scope (`403` otherwise, approved organizations only).

`cost_estimate_usd` is Talonic's own estimate of the underlying AI
provider's charge for the tokens billed. It is a different currency
than `GET /v1/usage/credits`, which reports the tenant's own
credit-ledger spend — the two do not reconcile against each other.

## Path parameters

- `id` string, uuid, required

## Query parameters

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

## Response `200`

Per-run usage breakdown (zero totals if still ingesting or failed pre-pipeline).

- RunUsageResponse
  - `run_id` string, uuid, required
  - `pipeline_id` string, uuid, nullable, required: Null while the run is still ingesting or if it failed before a pipeline was created — the response still returns `200` with zero totals in that case, never `404`.
  - `period` object, required
    - `from` string, date-time, required
    - `to` string, date-time, required
  - `scope` 'run_attributed_calls', required: Fixed code identifying the attribution rule applied to this response.
  - `scope_note` string, required: Human-readable statement of attribution: pipeline-stamped calls, limited to the run's own documents and active time window. Documented as approximate under shared-pipeline concurrency (append mode / several runs on one pipeline); a document skipped by dedup or extraction-reuse legitimately reports zeros. Explains the zero-totals case (still-ingesting/pre-pipeline run, or a legacy run predating per-request document tracking) when applicable.
  - `totals` object, required
    - `input_tokens` integer, required
    - `output_tokens` integer, required
    - `cache_read_tokens` integer, required
    - `cache_creation_tokens` integer, required: Cache-write tokens, billed at 1.25× the fresh input rate.
    - `calls` integer, required
    - `cost_estimate_usd` number, float, required
  - `breakdown` object[], required
    - `operation_type` string, required
    - `model` string, required
    - `input_tokens` integer, required
    - `output_tokens` integer, required
    - `cache_read_tokens` integer, required
    - `cache_creation_tokens` integer, required
    - `calls` integer, required
    - `cost_estimate_usd` number, float, required
  - `documents` object[], required: Per-document rollup, one row per entry in the run's own `documents[]` echo. A document skipped by dedup or extraction-reuse legitimately appears with all-zero counts.
    - `document_id` string, uuid, required
    - `filename` string, nullable: The document's filename. Omitted entirely (not merely null) on the zero-totals placeholder rows returned for a still-ingesting/pre-pipeline or legacy echo-less run.
    - `input_tokens` integer, required
    - `output_tokens` integer, required
    - `calls` integer, required
    - `cost_estimate_usd` number, float, required
  - `links` object, required
    - `self` string
    - `run` string

## Other responses

- `401`: Missing or invalid API key.
- `403`: The API key does not have the required scope.
- `404`: Either the run request is not owned by the caller's organization, or the organization lacks the "Cost control endpoints" approval (the route is hidden, not merely forbidden).
- `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)