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

# Per-pipeline API usage

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

## Request

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

Returns AI usage for one pipeline: totals, a breakdown by
`operation_type` × `model`, and a per-document rollup. `scope` is a
fixed code (`pipeline_calls_only`) and `scope_note` is the
human-readable statement of what this covers — pipeline-stamped
calls only. The ingest OCR leg (shared across runs, unstamped by
design) is excluded.

Requires the org's "Cost control endpoints" approval (superadmin-set;
organizations are approved by default, shared individual workspaces
are not) — unapproved organizations get a plain `404` (the
route's existence is not advertised) — AND an API key carrying the
`usage` scope (`403` otherwise, approved organizations only). The
toggle check runs before the scope check, so an unapproved org's
read-scoped key gets `404`, never a `403` that names the `usage`
scope.

`cost_estimate_usd` is Talonic's own estimate of the underlying AI
provider's charge for the tokens billed (cache-creation tokens price
at 1.25× fresh input, so the token math reconciles to the estimate).
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-pipeline usage breakdown.

- PipelineUsageResponse
  - `pipeline_id` string, uuid, required
  - `period` object, required
    - `from` string, date-time, required
    - `to` string, date-time, required
  - `scope` 'pipeline_calls_only', required: Fixed code identifying the attribution rule applied to this response.
  - `scope_note` string, required: Human-readable statement of what this response covers — pipeline-stamped calls only. The ingest OCR leg (shared across runs) is excluded by design.
  - `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 of the same pipeline-stamped calls.
    - `document_id` string, uuid, required
    - `filename` string, nullable, required: The document's filename, or null if it could not be resolved.
    - `input_tokens` integer, required
    - `output_tokens` integer, required
    - `calls` integer, required
    - `cost_estimate_usd` number, float, required
  - `links` object, required
    - `self` string
    - `pipeline` string

## Other responses

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