Cost Response Headers

Read extraction cost inline: every successful POST /v1/extract response carries X-Talonic-Cost-* headers with credits spent, EUR equivalent, and balance.

Cost response headers report what each extraction cost, directly on the extraction response. Every successful synchronous POST /v1/extract response includes X-Talonic-Cost-* headers with the credits consumed, the EUR equivalent, the remaining balance, and a breakdown of how fields were resolved, so AI agents can track spending without a separate API call.

Cost tracking is built into the extraction response to support autonomous agent workflows. Instead of polling a separate balance endpoint, agents read the cost headers inline and decide whether to trigger a top-up. The Cells-Resolved-Registry vs Cells-Resolved-AI breakdown shows how many fields were resolved from cached registry data (free) versus AI extraction (metered).

Response headers

X-Talonic-Cost-CreditsintegerCredits consumed for this extraction request.

X-Talonic-Cost-EURfloatEUR equivalent of credits consumed (at the configured rate).

X-Talonic-Balance-CreditsintegerRemaining credit balance after this request.

X-Talonic-Cells-Resolved-RegistryintegerNumber of fields resolved from the registry (no AI cost).

X-Talonic-Cells-Resolved-AIintegerNumber of fields resolved by AI extraction.

Example response headers

HTTP/1.1 200 OK
X-Talonic-Cost-Credits: 70
X-Talonic-Cost-EUR: 0.07
X-Talonic-Balance-Credits: 64930
X-Talonic-Cells-Resolved-Registry: 0
X-Talonic-Cells-Resolved-AI: 1

Agents can read these headers after every extraction to decide whether to call POST /v1/billing/topup to replenish credits.

Registry-resolved cells are free because the value was already known from a previous extraction. Over time, as your field registry grows, more cells resolve from the registry and fewer require paid AI extraction.

Frequently asked questions

Are cost headers included on async (202) responses?+

No. Cost headers are only included on synchronous 200 responses where extraction completes immediately. Async responses return a poll URL instead.

Are cost headers included on batch extraction responses?+

No. Batch extraction (processing_mode=batch) defers extraction to the provider batch API. Cost is calculated when the batch completes, not at upload time.

What is the credit-to-EUR conversion rate?+

The standard rate is 1,000 credits per EUR, so one credit equals EUR 0.001. The unauthenticated `GET /v1/pricing` endpoint returns the current rate as `credits_per_eur` together with the full per-unit credit catalog.

Cost Response Headers

Frequently asked questions

Related