Usage Receipts

Usage receipts are opt-in. Send these headers with any billable request:

x-llmgateway-usage-contract: 1
x-llmgateway-operation-id: YOUR_UNIQUE_OPERATION_ID

The operation ID is optional, 1–512 characters of A-Z a-z 0-9 _ . : -, and lets you find the receipt again after a dropped connection. Reusing an operation ID returns 409 unless its earlier request was rejected before reaching a provider.

Receipts cover chat completions, messages, responses (and compact), embeddings, decisions, image generations and edits, speech, transcriptions, videos, moderations, rerank, OCR and search.

Response headers

• x-llmgateway-receipt-id: the receipt of this request.
• x-llmgateway-usage: the receipt itself, as base64url-encoded JSON, whenever the cost is known when the response is sent. Binary audio replies carry their cost only here.

JSON replies also carry the cost as usage.cost. Streams and video jobs have only the receipt ID: their receipt is pending until the stream ends or the job finishes.

Retrieve a receipt

GET /v1/usage/receipts/{receiptId or operationId}
Authorization: Bearer YOUR_API_KEY

The key must belong to the project that made the request. Receipts are kept for 30 days; an unknown receipt is not proof of zero usage.

interface UsageReceipt {
	v: 1;
	receiptId: string;
	operationId: string | null;
	operation: string; // e.g. "chat.completions", "audio.speech", "videos"
	model: string | null;
	state: "pending" | "final";
	costUsd: string | null; // exact decimal USD at list price, null while pending
	usage: Record<string, number>; // e.g. input_tokens, output_tokens
	pricingVersion: "llmgateway-list-v1";
	createdAt: string;
	expiresAt: string;
	resourceId?: string; // the video job ID
	notDispatched?: true; // rejected before any provider; costUsd is "0"
}

costUsd is the same figure as usage.cost on the response. A video receipt becomes final once the job has finished and been billed.