Skip to content

Spending limits for OpenAI calls in Python

OpenAI Chat Completions and the Responses API, sync and async, non-streaming and streaming. Chat Completions: Verified locally with synthetic provider transports and real local KazenAI services, and also verified against the live OpenAI and Anthropic APIs on 2026-10-12 (gpt-6-luna, claude-sonnet-5-5).

from kazenai_finops import monitor, BudgetExceeded
import openai
client = monitor(openai.OpenAI(max_retries=0), agent_id="support", max_budget_usd=1.0)
# Non-streaming
client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Hello"}],
)
# Streaming — use a context manager for deterministic early-close cleanup
with client.chat.completions.create(
model="gpt-4o-mini",
stream=True,
messages=[{"role": "user", "content": "Hello"}],
) as stream:
for chunk in stream:
pass
# The official lazy helper is also supported. Reservation begins on __enter__,
# not when the manager object is constructed.
with client.chat.completions.stream(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Hello"}],
) as stream:
stream.until_done()

monitor() merges stream_options={"include_usage": true} while preserving caller-supplied stream options. OpenAI documents the final usage chunk as an extra chunk whose choices list is empty. KazenAI uses that authoritative usage to settle actual cost. KazenAI records provider_started before dispatch. Closing early, a provider error after the stream started, or receiving no final usage records outcome_unknown and leaves the shared reservation pending reconciliation. A provider that refuses the request outright (HTTP 4xx such as a bad request, invalid key, unknown model or rate limit) generated nothing, so that call settles at exactly $0 and its hold is released.

Optional stream_cutoff_usd estimates observed output cost and attempts to close the upstream stream when the threshold is reached. It is a local safety guard, not a guarantee about provider-side generation or final billing.

Wrap openai.AsyncOpenAI the same way and await the calls. Admission and settlement are native async; a denied reservation raises BudgetExceeded before any request is sent.

import asyncio
import openai
from kazenai_finops import monitor, BudgetExceeded
async def main() -> None:
client = monitor(openai.AsyncOpenAI(max_retries=0), agent_id="support", max_budget_usd=1.0)
try:
resp = await client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Hello"}],
)
stream = await client.chat.completions.create(
model="gpt-4o-mini",
stream=True,
messages=[{"role": "user", "content": "Hello"}],
)
async for chunk in stream:
pass
except BudgetExceeded as exc:
print(f"Denied before dispatch: {exc}")
finally:
await client.close()
asyncio.run(main())

Both calls send the same prompt. That’s fine: by default the loop guard records a repeat and sends it. With monitor(..., loop_guard="block") the second call raises LoopDetected (from kazenai import LoopDetected) before dispatch, so catch it next to BudgetExceeded. See Repeated requests.

New in 1.2.0: responses.create, responses.parse and responses.stream, sync and async, non-streaming and streaming, with function tools. Tested with the official SDK (openai 1.109.1 and 2.54.0) and verified against the live OpenAI API on 2026-10-13 (gpt-6-luna, gpt-6.1-sol): parse, create, streaming and the stream() helper, sync and async, with recorded cost equal to the published price for the reported tokens.

from kazenai_finops import monitor, BudgetExceeded
import openai
client = monitor(openai.OpenAI(max_retries=0), agent_id="support", max_budget_usd=1.0)
resp = client.responses.create(model="gpt-4o-mini", input="Hello")
with client.responses.stream(model="gpt-4o-mini", input="Hello") as stream:
final = stream.get_final_response()
  • monitor() sets max_output_tokens from the model’s output bound when you leave it out, and lowers a larger value to that bound. It also bounds reasoning tokens, which OpenAI counts inside output_tokens.
  • Responses streams report usage only on the final event (response.completed, response.incomplete or response.failed); KazenAI settles exact cost from it. A failed response without usage stays pending reconciliation, never $0.
  • responses.stream() reserves once, on __enter__.

These requests raise UnsupportedModeError before anything is sent, because their cost cannot be bounded before the call:

Request error_code Why
background=True responses_background_unsupported Returns before usage exists
previous_response_id, conversation, stored prompt responses_server_state_unsupported The input stored on OpenAI’s side cannot be priced first; send the conversation as input items
Built-in tools (web_search, file_search, code_interpreter, image_generation, computer_use, mcp, …) responses_builtin_tool_unsupported Billed outside token usage
responses.stream(response_id=...) responses_background_unsupported Resumes a background response

LangChain ChatOpenAI(use_responses_api=True) is still rejected; bind Chat Completions for framework paths.

Surface Status
Realtime / WebSocket (client.realtime, client.beta.realtime) UNSUPPORTED — raises UnsupportedModeError on a monitored client
Legacy Completions (client.completions) UNSUPPORTED — raises UnsupportedModeError on a monitored client
Responses compact / connect UNSUPPORTED — raises UnsupportedModeError on a monitored client
Embeddings, Images, Audio, Batches, Fine-tuning, Assistants, vector stores UNSUPPORTED — raises UnsupportedModeError on a monitored client (since 1.2.0)
A method, with_raw_response wrapper or client.request saved before monitor() UNSUPPORTED — refused before dispatch; read methods from the client after wrapping

Reads, deletes and free endpoints (files, uploads, moderations, token counting, cancel) still work. To send an endpoint without a budget check, name it; that spend is not counted:

client = monitor(OpenAI(max_retries=0), max_budget_usd=5, allow_unmetered=("/embeddings",))

Control covers what is sent through a monitored client. Code that holds the API key and creates another client, or sends raw HTTP, is outside it.

See the full matrix: Supported surfaces.