Receipts

Each job has one receipt. It records what you asked for, which offer won, what the job used, what it cost and how fast it ran. The exchange writes it just after it answers. A receipt is final once its settlement_status is settled, credited or released.

Use the receipt to check a charge. supplier_charge_usd plus fee_usd, less credits_usd, is buyer_charge_usd. Fees explains the fee.

Read a receipt

• GET /v1/jobs/{job_id}: one receipt. The job ID is in the x-liquid-job-id header and in exchange.job_id.
• GET /v1/exchange/receipts: your receipts, newest first. It takes limit, cursor, model and outcome (comma-separated lists for the last two) and returns receipts and next_cursor.
• The console shows the same receipts with filters and charts. The list_receipts MCP tool lists them for an agent.

A key with read scope or higher can call these routes. A job of another workspace returns 404. A call at once after the answer can also return 404. Try again after a moment.

curl "https://router.inference.ai.exchange/v1/exchange/receipts?limit=20&outcome=completed" \
  -H "Authorization: Bearer $LIQUID_API_KEY"

A stored receipt is one flat JSON object. A receipt for a job with a winner also has the exchange block of the live response, and can have requested_purchase. An absent field does not apply to the job. It is not zero. Money fields are USD numbers. A rate is USD per million tokens.

The exchange block

The exchange block of a live response has a charge object and a usage object. They name the same money as the fields below.

• Each amount has two fields. supplier_usd is a JSON number in USD. supplier_nanos is the same amount as an integer of nano-USD, so it is exact. cap, estimated, supplier, fee, credits and total each have both fields.
• supplier_* is what the provider earns, before the exchange fee. total_* is what you paid: supplier plus fee, less credits.
• usage counts tokens as prompt_tokens, cached_tokens, cache_write_tokens and completion_tokens. reasoning_tokens appears when the provider reports it.
• usage.pricing lists the use by billable. See Usage below.

"charge": { "cap_nanos": 50000000, "supplier_nanos": 1200000, "fee_nanos": 60000, "credits_nanos": 0, "total_nanos": 1260000 },
"usage": { "prompt_tokens": 120, "completion_tokens": 40, "pricing": [{ "billable": "output_text", "unit": "mtok", "quantity": 40, "usd": 0.000019 }] }

Identity

• job_id: one logical request has one job.
• award_id: the award of the job to an offer. Empty when no offer took the job. It is also the idempotency key that the provider receives.
• tenant, key_id: your workspace and the API key. key_id is absent for a job from the console.
• client: the program that sent the job: name and version.
• cost_tag: the label from your x-liquid-tag header. A provider never sees it.
• applied_preset, named_preset: the preset that the key applied, and the preset that you named as model, each with its revision.
• workload: the workload profile of the job. Absent when the profile names no stored workload.
• requested_model: the name that you sent as model. A job with no award has no addressing, so this is its only model name.
• created_at, settled_at: when the exchange received the job, and when it settled.

Outcome

• outcome: how the job ended. See below.
• settlement_status: the state of the money. See below.
• service: met, missed, failed, pending, unknown, not_started or single_supplier_refused.
• finish_reason: stop, length (the answer reached the output limit) or tool_calls. Absent when no output came.
• shortfall: needed_usd and balance_usd. Present only when your balance excluded every offer that could take the job.
• output_limit: asked_tokens and applied_tokens. Present when the exchange lowered your output limit so that an offer could take the job.
• reasoning_effort: asked and sent. They differ when the offer accepts other levels and the exchange sent the nearest one sent is absent when the offer takes no level.

outcome and what each value charges:

settlement_status:

• reserved: the exchange holds the price cap. The job is not settled yet.
• settled: the job was charged.
• credited: the job was charged and then credited back.
• pending: usage is missing or in conflict. You get a credit after the deadline. The exchange does not bill you without a warning.
• released: the hold went back to your balance. You paid nothing.

A job that missed its deadline is charged like any other completed job. credits_usd is zero.

Charge

• cap_usd: the most the job could cost, locked before the first token. Also the x-liquid-cap-usd header.
• estimated_charge_usd: the cold estimate that ranked the offer, before any cache credit.
• cache_credit: hit_rate, source (buyer or measured) and credit_usd. Ranking uses it. The cap, the hold and the charge do not.
• supplier_charge_usd: what the provider earns, before the exchange fee.
• fee_usd: the exchange fee, after any referral discount. See Fees. fee_discount_usd is the part that a referral discount took off.
• credits_usd: credit that the exchange gave back for the job.
• buyer_charge_usd: what you paid. It never exceeds cap_usd.
• charge_split: what the input, cache reads, cache writes and output each cost, fee included, as tokens and usd. Absent for a job not priced in tokens. When the cap limited the job, the parts add up to buyer_charge_usd plus cap_held_usd.
• cap_held_usd: what the cap took off the metered charge, fee included. Present only when the job used more than its cap. The provider carries it.
• uncached_charge_usd, cache_charge_usd: the charge if all input had the uncached rate, and the part that cache reads and writes cost. Present only when some input used a cache. For information only.
• rates: the rates that priced the job: uncached_input, cache_read, cache_write_short, cache_write_long and generation. They stay as at award time if the provider changes them later.
• web_search: the search that you asked for with :web. Its charge_usd is part of fee_usd and buyer_charge_usd.

Usage

• meters: what the provider reported, in its own tokenizer. See below.
• reasoning_tokens: hidden reasoning tokens, billed as output. Present only when the provider reports them.
• tokenizer_id, rate_schema_version: the tokenizer that counted the tokens, and the rate table that priced the job.
• usage_provenance: the upstream usage report, unchanged. On a failed job it holds an error. Null for some media jobs.
• answer_checks: what the exchange checked in the answer. See below. Absent means not checked, and you must not count it as a pass.

meters fields. A media meter is absent when it is zero.

• uncached_input: input tokens that no cache served or kept.
• cache_read: input tokens that a cache served.
• cache_write_short, cache_write_long: input tokens written to the cache, by lifetime.
• generation: output tokens, reasoning included. audio_generation is the audio part.
• images, characters, video_seconds, audio_seconds: the quantity of an image, speech, video or transcription job. Not tokens.

The exchange.usage block gives the same numbers in a simpler form. prompt_tokens is the sum of all input meters.

exchange.usage.pricing lists the same use by billable. Each line has billable, unit, quantity and usd. The usd is the provider charge for that quantity before the exchange fee, at the rate that priced the job. A receipt with no stored rates has no table. The flat counters stay.

answer_checks changes no charge, except that a chat answer with a bad tool call is rejected before you receive it.

• structured_output.result: the check against your response_format: passed, not_json, schema_mismatch, cut, refused or unchecked. keyword names the broken JSON Schema keyword for schema_mismatch. See Structured output.
• tool_calls, tool_call_errors: the tool calls in the answer, and how many were bad. See Tool calls.
• tool_call_faults: the bad calls by kind: invalid_json, unknown_name, schema_mismatch.
• tool_markup: 1 when the text has tool-call markup but the answer has no tool call.

Timing

• ttft_ms: time to first token. It starts when the request arrives, so it includes the auction.
• completion_ms: time from the first byte to the last.
• promised_ttft_ms: the first-token time that the offer promised. The receipt keeps it.
• ttft_limit_ms: your limit. Absent for an image job and for old receipts.
• ttft_deadline_ms: ttft_limit_ms plus 1 second for each 10,000 input tokens. The exchange judges the job against this, not against the promise. A job with a ttft_ms above promised_ttft_ms can still be met.

Provider and offer

• provider_id: the provider, stable when it changes its slug. provider_slug: its slug at the time.
• offer_id: the offer that served the job. Use it to trace a charge.
• provider_attribution: what the provider said about its data handling at award time. Each claim has a basis (declared or checked), checked_at and valid_until. The receipt freezes it.

Addressing

addressing says how your request became a served model. It is absent on a job with no award.

• requested, target: the name that you sent, and what it is: a model, a router or a preset.
• match_type: exact, approved_set, router or auto.
• router, router_version: the router model that chose the models, and the Auto mode version.
• served_model, served_precision: the model that answered, and its precision, such as bf16 or fp4. provider-managed means the provider does not state it.
• auto: why Auto chose the model. See Auto Router. auto_fallback: why a call to a router model ranked by price and not by Auto.
• synthetic (a local substitute answered), unverified (no operator reviewed the deployment) and probe (the exchange sent the job to measure a deployment): do not use such a job as evidence about a model.

Competition

• clearing_rule: how the price was set. first_price charges the locked rates of the winner, up to its cap.
• offers_considered, offers_eligible: the offers that the gate looked at, and those that passed.
• suppliers_eligible, single_supplier: the independent providers behind the eligible offers, and whether only one was eligible.
• eligibility.excluded: each offer that the gate refused, with provider, offer_id, reason and, when it helps, detail. exchange.routing.eligibility gives the same as counts for each provider and reason.

reason values:

• job_kind_not_served, model_not_served: the offer does not make this kind of output, or this model.
• feature_unsupported, media_unsupported: the deployment cannot do a feature or accept an attachment. detail names it.
• context_too_large, output_bound_unsupported: the prompt, your output limit, or a media size is outside what the offer allows.
• recently_failed: the model failed a job recently, or health samples show it down.
• service_too_slow, throughput_too_low: the offer's promised deadline is too slow for your limit.
• cap_exceeds_buyer_cap, cap_exceeds_budget: the worst-case charge is above your cap_usd, or your balance.
• rate_above_ceiling, above_cost_tier: the published rate is above your maximum rate or cost tier.
• region_policy, retention_policy, provider_requirements: the provider does not meet your region, data-retention or provider-claim rules.
• model_not_allowed, provider_not_allowed, vendor_not_allowed, provider_blocked: your model list, provider list, creator list or block list excludes the offer.
• offer_expired, pinned_offer_not_resting: the offer is no longer on the book.
• workload_profile_not_targeted: the offer is outside the workload profile that you named.
• superseded_by_own_offer: the same provider had a lower offer that also qualified.
• score_unmapped, score_missing: Auto has no approved score for the deployment, or for the task.

Exchange block and requested purchase

exchange is the block of the live response. See Purchasing rules. requested_purchase is what the request asked for before the preset of its key limited it: target, models, strategy, rules and sources. Absent on old jobs.

Check a receipt

1. Add supplier_charge_usd and fee_usd, subtract credits_usd, and compare with buyer_charge_usd. It must not exceed cap_usd.
2. For a job priced in tokens, multiply each meters value by the matching rate in rates. The sum is supplier_charge_usd, unless the cap limited the job.
3. Compare fee_usd with Fees.
4. Compare ttft_ms with ttft_deadline_ms, not with promised_ttft_ms.