Usage

Per-pipeline API usage

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.

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)

Path parameters

idstring uuid required
Example:a1b2c3d4-e5f6-7890-abcd-ef1234567890

Resource UUID.

Query parameters

fromstring date-time

Start of the reporting window (ISO 8601). Default 90 days ago.

tostring date-time

End of the reporting window (ISO 8601). Default now.

Response

Per-pipeline usage breakdown.

pipeline_idstring uuid required
scope'pipeline_calls_only' required

Fixed code identifying the attribution rule applied to this response.

scope_notestring required

Human-readable statement of what this response covers — pipeline-stamped calls only. The ingest OCR leg (shared across runs) is excluded by design.

Example response

{
  "pipeline_id": "b3c4d5e6-f7a8-9012-bcde-f34567890123",
  "period": {
    "from": "2026-04-25T14:30:00.000Z",
    "to": "2026-04-25T14:30:00.000Z"
  },
  "scope_note": "Calls stamped with this pipeline id in call metadata. The shared ingest OCR leg is excluded."
}

Changes

No recorded changes to this operation across all 1 revision of this API.