Responses API Per-Run Spending Controller Guide

Quick answer

For an agent that may call the Responses API several times, use a per-run reserve-and-settle ledger:

1. verify the exact model, default service tier, prices, and request bounds;
2. count the real input before each call;
3. reserve the highest possible input plus output token cost;
4. make the request with matching model and input;
5. validate returned model, tier, status, and usage;
6. settle actual cost and release unused reservation;
7. block the run when cost or completion is uncertain.

This pattern helps decide whether one task can afford its next request. It is not an OpenAI invoice, organization-wide spending cap, or substitute for project limits and reconciliation.

The accounting state

Track exact amounts rather than binary floating point:

Field	Meaning
maximum	Approved model-token budget for the run
spent	Settled cost from validated returned usage
pending	Worst-case cost reserved for submitted requests
holds	Unique reservation handles preventing double settlement
blocked	Permanent stop until external reconciliation or a new authorized run

The invariant is:

spent + pending <= maximum

For concurrent workers, reserve in one atomic operation in shared durable storage. A process-local lock protects only one process.

Verify the rate card

Bind these facts together:

• exact model ID, not an alias;
• default service tier for the Cookbook pattern;
• ordinary, cached, cache-write where separately billed, and output prices;
• maximum input and output tokens;
• official source and verified_at date;
• example_only=false and an explicit approval state.

The official Cookbook’s prices, token counts, model name, and limits are fictional. Do not copy them into production. A verification date records when someone checked a rate; it does not keep the rate current.

Count and reserve before the request

Use the input-token counting endpoint with the same model and supported input fields used for generation. Include instructions, tools, images, files, and history in both paths when they are part of the request.

Reserve conservatively:

input_tokens × highest possible input rate + max_output_tokens × output rate

This covers ordinary, cached, or separately billed cache-write input when the controller cannot know the mix before the response. Reject the request if the reservation exceeds remaining budget.

Settle returned usage

After a completed response, verify:

• returned model equals the pinned model;
• returned service tier equals the configured tier;
• input, cached, cache-write, output, and total fields are present and nonnegative;
• total equals input plus output;
• cached plus written input does not exceed total input;
• usage stays within configured bounds;
• actual cost does not exceed the hold.

Then move the actual amount into spent and release the difference from pending.

Reasoning tokens are included in output totals in the documented pattern. Avoid charging them twice.

Fail closed on uncertainty

Block the run when:

• a timeout or interruption occurs after submission;
• the response is incomplete, queued, or unexpected;
• usage or token details are missing or inconsistent;
• model or service tier differs;
• actual spend exceeds the reservation;
• a separately priced category lacks a verified rate;
• retries may have created another billable request.

A timeout does not prove that the provider stopped processing. Keep the reservation until provider usage is reconciled. Use idempotent application effects so a retry cannot duplicate a consequential tool action.

Costs outside the sample controller

The Cookbook controller covers synchronous, non-streaming, default-tier model-token cost only. Add separate contracts for:

• hosted tools such as web search;
• streaming and partial delivery;
• background requests and later final usage;
• non-default processing tiers;
• regional and long-context rates;
• storage and server-managed agent runs;
• network, compute, human review, and third-party tools;
• account-specific discounts, taxes, or commitments.

Do not silently set these to zero. Either price and reserve them, prohibit them for the bounded run, or block with a precise reason.

Project controls and reconciliation

Project spending limits are broader controls and may not take effect immediately. Alerts notify; they do not stop requests. The Costs API returns daily aggregated costs, not real-time task affordability.

Reconcile the run ledger with provider usage and invoice data using run, project, model, and request identifiers where available. Investigate missing, duplicated, late, or differently categorized charges.

Production acceptance tests

1. Exact-budget successful call.
2. Next reservation exceeds balance and no request is sent.
3. Concurrent workers cannot reserve the same funds.
4. Timeout after submission blocks the run.
5. Missing usage, unexpected model, or tier blocks the run.
6. Incomplete response settles known cost and remains blocked.
7. Retry is disabled or accounted as a distinct reservation.
8. Hosted tools and background mode are rejected unless separately supported.
9. Provider reconciliation detects a ledger mismatch.

Use the agent run budget readiness tool before enabling the controller.

Frequently asked questions

What is a per-run spending controller?

It is an application control that gives one task a budget, reserves the worst-case token cost before each request, settles returned usage, and stops before the next request would exceed the remaining amount.

Is the controller an OpenAI billing hard limit?

No. It is an application estimate. Project limits cover broader spend and can lag, alerts do not stop requests, and the Costs API reports daily totals rather than whether one task can afford its next request.

What should happen when request cost is uncertain?

Fail closed: block the run, keep the reservation unavailable, and reconcile provider usage before deciding whether any further call is safe.

Official sources

• OpenAI Cookbook: Build a per-run spending controller
• OpenAI API pricing
• OpenAI models
• OpenAI project spending limits
• OpenAI Costs API

Source check: August 19, 2026. Recheck SDK, model, service tier, token counting, usage fields, prices, cache billing, tools, retries, data controls, project limits, and reconciliation before deployment.