Usage

Per-run API usage

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.

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)

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-run usage breakdown (zero totals if still ingesting or failed pre-pipeline).

run_idstring uuid required
pipeline_idstring 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.

scope'run_attributed_calls' required

Fixed code identifying the attribution rule applied to this response.

scope_notestring 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.

Example response

{
  "run_id": "c4d5e6f7-a8b9-0123-cdef-456789012345",
  "period": {
    "from": "2026-04-25T14:30:00.000Z",
    "to": "2026-04-25T14:30:00.000Z"
  },
  "scope_note": "Calls stamped with the run's pipeline id, restricted to the run's own documents and lifetime. Approximate under shared-pipeline concurrency (append mode); the shared ingest OCR leg is excluded."
}

Changes

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