Usage Overview

Track AI token consumption and cost estimates across your workspace with aggregate usage stats and per-document breakdowns via the Talonic Usage API endpoints.

The Usage API provides visibility into AI token consumption and cost estimates across your workspace. Every AI operation — extraction, classification, matching, resolution — is metered and logged with input/output token counts, the model used, and an estimated USD cost. Use these endpoints to monitor spending, optimize pipeline configuration, and audit AI operations.

Four endpoints cover aggregate, document, pipeline, and run views. The aggregate endpoint returns workspace-wide totals with a breakdown by operation type and model over a configurable date range. The per-document endpoint drills into a specific document to show every AI call made during its processing lifecycle, including cache token utilization and per-operation cost estimates. The per-pipeline and per-run endpoints (below) narrow the same accounting to one pipeline or one /v1/run request, so a single Spec run or a single ingest call can be costed in isolation.

Cost estimates are computed from the model-specific token pricing at the time of the API call. Input tokens, output tokens, cache read tokens, and cache creation tokens are each priced at their respective rates — cache creation (prompt cache writes) bills at 1.25× the fresh input rate. Cache read tokens represent prompt cache hits where previously cached input was reused at a significantly lower rate than fresh input tokens — high cache utilization indicates efficient prompt reuse across similar documents.

Usage data is available immediately after each AI operation completes. There is no delay or batching — the token counts and cost estimates are recorded synchronously as part of the operation lifecycle. Historical data is retained indefinitely and can be queried over any date range.

cost_estimate_usd (returned by the document, pipeline, and run endpoints) is Talonic's own estimate of the underlying AI provider's charge for the tokens billed on that call — a provider-cost figure, computed from model-specific per-token pricing. It is a different currency from GET /v1/usage/credits, which reports your organization's own credit-ledger consumption (the price Talonic charges you). The two numbers do not reconcile against each other: one estimates what Talonic pays its model provider, the other reports what your workspace spent in credits.

Aggregate Response

{
  "period": { "from": "2026-04-14T00:00:00.000Z", "to": "2026-05-14T00:00:00.000Z" },
  "totals": { "input_tokens": 8940120, "output_tokens": 1274580, "cache_read_tokens": 3120040, "cache_creation_tokens": 421800, "calls": 2764 },
  "breakdown": [
    {
      "operation_type": "extraction",
      "model": "claude-sonnet-4-20250514",
      "input_tokens": 7896420,
      "output_tokens": 1127040,
      "cache_read_tokens": 2988100,
      "cache_creation_tokens": 398200,
      "calls": 1842
    },
    {
      "operation_type": "classification",
      "model": "claude-haiku-3-5",
      "input_tokens": 1043700,
      "output_tokens": 147540,
      "cache_read_tokens": 131940,
      "cache_creation_tokens": 23600,
      "calls": 922
    }
  ],
  "links": { "self": "/v1/usage" }
}

Per-Document Usage

The per-document endpoint returns every AI operation performed on a specific document along with token counts, cache utilization, and cost estimates. This is useful for understanding why a particular document was expensive to process — for example, a large multi-page PDF that required multiple extraction chunks, or a document that triggered classification retries.

Document Response

{
  "document_id": "d4e5f6a7-b8c9-0123-d456-e7f8a9b0c1d2",
  "totals": {
    "input_tokens": 12480,
    "output_tokens": 1890,
    "cache_read_tokens": 2048,
    "cache_creation_tokens": 1024,
    "cost_estimate_usd": 0.058,
    "calls": 3
  },
  "entries": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "operation_type": "extraction",
      "model": "claude-sonnet-4-20250514",
      "input_tokens": 8640,
      "output_tokens": 1245,
      "cache_read_tokens": 2048,
      "cache_creation_tokens": 1024,
      "cost_estimate_usd": 0.041,
      "created_at": "2026-05-13T14:22:10.000Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "operation_type": "classification",
      "model": "claude-haiku-3-5",
      "input_tokens": 3840,
      "output_tokens": 645,
      "cache_read_tokens": 0,
      "cache_creation_tokens": 0,
      "cost_estimate_usd": 0.017,
      "created_at": "2026-05-13T14:21:45.000Z"
    }
  ],
  "links": {
    "self": "/v1/usage/documents/d4e5f6a7-b8c9-0123-d456-e7f8a9b0c1d2",
    "document": "/v1/documents/d4e5f6a7-b8c9-0123-d456-e7f8a9b0c1d2"
  }
}

Per-Pipeline Usage

The per-pipeline endpoint returns AI usage for one pipeline: totals, a breakdown by operation type and model, and a per-document rollup. This is the view to reach for when you want to cost a single Spec run in isolation — for example, comparing the actual spend of two pipeline configurations, or checking a pipeline against a budget before scaling it up.

Pipeline Response

{
  "pipeline_id": "b3c4d5e6-f7a8-9012-bcde-f34567890123",
  "period": { "from": "2026-04-22T00:00:00.000Z", "to": "2026-07-21T00:00:00.000Z" },
  "scope": "pipeline_calls_only",
  "scope_note": "Calls stamped with this pipeline id in call metadata. The shared ingest OCR leg is excluded.",
  "totals": {
    "input_tokens": 428900,
    "output_tokens": 61240,
    "cache_read_tokens": 112000,
    "cache_creation_tokens": 18500,
    "calls": 96,
    "cost_estimate_usd": 2.14
  },
  "breakdown": [
    {
      "operation_type": "extraction",
      "model": "claude-sonnet-4-20250514",
      "input_tokens": 402100,
      "output_tokens": 57980,
      "cache_read_tokens": 112000,
      "cache_creation_tokens": 18500,
      "calls": 84,
      "cost_estimate_usd": 2.01
    },
    {
      "operation_type": "resolution",
      "model": "claude-haiku-3-5",
      "input_tokens": 26800,
      "output_tokens": 3260,
      "cache_read_tokens": 0,
      "cache_creation_tokens": 0,
      "calls": 12,
      "cost_estimate_usd": 0.13
    }
  ],
  "documents": [
    {
      "document_id": "d4e5f6a7-b8c9-0123-d456-e7f8a9b0c1d2",
      "filename": "invoice-04521.pdf",
      "input_tokens": 12480,
      "output_tokens": 1890,
      "calls": 3,
      "cost_estimate_usd": 0.058
    }
  ],
  "links": {
    "self": "/v1/usage/pipelines/b3c4d5e6-f7a8-9012-bcde-f34567890123",
    "pipeline": "/v1/pipelines/b3c4d5e6-f7a8-9012-bcde-f34567890123"
  }
}

Per-Run Usage

The per-run endpoint returns AI usage for one /v1/run request — the same shape as the per-pipeline endpoint, keyed by the run request id instead of the pipeline id. Use it when you submitted documents through POST /v1/run and want to cost that specific call, independent of whatever else is happening on the underlying pipeline.

A run that is still ingesting, or that failed before a pipeline was created, has a null pipeline_id; the endpoint still returns 200 with zero totals and a scope_note explaining why, rather than 404, since pollers hit this window constantly. A legacy run request that predates per-request document tracking (no documents[] echo recorded) returns the same zero-total shape with its own scope_note, even when pipeline_id is set. Attribution otherwise intersects the run's pipeline stamp, the run's own documents[] echo, and the run's active time window (open-ended while the run is live; bounded a few minutes past updated_at once terminal) — 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 up with all-zero counts.

Run Response

{
  "run_id": "c4d5e6f7-a8b9-0123-cdef-456789012345",
  "pipeline_id": null,
  "period": { "from": "2026-04-22T00:00:00.000Z", "to": "2026-07-21T00:00:00.000Z" },
  "scope": "run_attributed_calls",
  "scope_note": "No pipeline exists for this run yet (still ingesting, or failed before pipeline creation) — no attributable LLM calls.",
  "totals": {
    "input_tokens": 0,
    "output_tokens": 0,
    "cache_read_tokens": 0,
    "cache_creation_tokens": 0,
    "calls": 0,
    "cost_estimate_usd": 0
  },
  "breakdown": [],
  "documents": [
    { "document_id": "d4e5f6a7-b8c9-0123-d456-e7f8a9b0c1d2", "input_tokens": 0, "output_tokens": 0, "calls": 0, "cost_estimate_usd": 0 }
  ],
  "links": {
    "self": "/v1/usage/runs/c4d5e6f7-a8b9-0123-cdef-456789012345",
    "run": "/v1/run/c4d5e6f7-a8b9-0123-cdef-456789012345"
  }
}

Example Request

curl "https://api.talonic.com/v1/usage?from=2026-06-26T00:00:00Z&to=2026-07-03T00:00:00Z" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

curl "https://api.talonic.com/v1/usage/pipelines/b3c4d5e6-f7a8-9012-bcde-f34567890123" \
  -H "Authorization: Bearer $TALONIC_USAGE_SCOPED_KEY"

Errors