Spending limits for OpenAI calls in Python
Supported in 1.2.0
Section titled “Supported in 1.2.0”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, BudgetExceededimport openai
client = monitor(openai.OpenAI(max_retries=0), agent_id="support", max_budget_usd=1.0)
# Non-streamingclient.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": "Hello"}],)
# Streaming — use a context manager for deterministic early-close cleanupwith 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 openaifrom 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.
Responses API
Section titled “Responses API”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, BudgetExceededimport 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()setsmax_output_tokensfrom 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 insideoutput_tokens.- Responses streams report usage only on the final event (
response.completed,response.incompleteorresponse.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.
Not supported
Section titled “Not supported”| 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.
