One ceiling per task_ref. Not per project, not per calendar month.
Every call sharing a task_ref consults one ceiling before it runs, in units you define. The call that would cross it gets approved: false.
pip install agentbill-sdknpm install agentbillfree tier1,000 preflight calls/mono cardkey in 30 seconds
from agentbill import AgentBillClient
client = AgentBillClient(
api_key="agb_your_key")
# You decide what a unit is worth.
# job-142 gets 500 of them, across
# every call passing this task_ref.
client.preflight(agent_id="researcher",
task_ref="job-142",
task_ceiling=500,
estimated_units=12)
# your provider call goes here
# settle, or the units stay held
# until the reservation expires.
client.record(agent_id="researcher",
task_ref="job-142",
units=12)
>>> run 42 of the retry loop:
import { preflight, record }
from 'agentbill'
// Reads AGENTBILL_API_KEY from env.
// You decide what a unit is worth.
// job-142 gets 500 of them, across
// every call passing this taskRef.
await preflight({ agentId: 'researcher',
taskRef: 'job-142',
taskCeiling: 500,
estimatedUnits: 12 })
// your provider call goes here
// settle, or the units stay held
// until the reservation expires.
await record({ agentId: 'researcher',
taskRef: 'job-142',
units: 12 })
// run 42 of the retry loop:
{ "approved": false, "reason": "task_ceiling_exceeded", "estimated_units": 12, "task_ref": "job-142", "task_ceiling": 500, "task_used_units": 492, "task_remaining_units": 8 }
The SDK raises TaskCeilingExceededError. Your code decides what happens next.
Try it · runs in your browser
Run an agent into its ceiling.
Set a ceiling for the whole job and run the agent. The call that would cross it gets approved: false, with the same body your SDK gets.
Same rule and same response body as POST /preflight.
Why a task, not a month
Your job is not an account, and it does not last a month.
The provider cap is real and it fires. It is bound to a project, to an organization over a calendar month, or to one session on the vendor's own harness. A run too small to move a monthly number never trips it. A number low enough to catch that run stops every agent in the organization until the month turns.
A hard limit answers 429 project_spend_limit_exceeded, and enforcement “is not instantaneous, so recorded spend can slightly exceed the configured amount.” The boundary is the project or the organization.
developers.openai.comA tier spend cap pauses API usage “until 00:00 UTC on the first day of the next month.” The boundary is the organization, and the clock is the calendar.
platform.claude.comEnterprise plan, $3,000/month limit: “~$300 of unintended API usage over a single weekend with no way to detect or stop it from the CLI.” The limit is a month. The incident was a weekend.
github.comRead at source on 2026-09-07. What differs is not whether a cap fires. It is what the cap is bound to.
Per-task ceilings
One job, many calls, one ceiling.
Pass task_ceiling on the first call and the same task_ref on every call after it. The first call fixes the ceiling. Each one consults it before it runs, in units you define.
Watch budgets burn down →No proxy
Two calls. Nothing in your request path.
preflight before your provider call, record after it. No base URL to change, no traffic routed through us, no provider keys held. If we are unreachable, the SDK raises inside your process and your code decides.
How the reservation works →The receipt
Every refusal is written down.
Each approved: false is persisted with the body the agent received, per agent and per task. A record that lands past a ceiling because preflight was skipped is kept as a leak, not hidden.
See the refusals →Keys
Keys you can revoke in one call.
Revoke, and the key is refused on its next request. Rotate, and the old key works for 24 hours, then revokes itself. Labels, expiry in days, 100 requests a minute per key, and an email when a key is used from a new address. Your provider keys never touch us.
See the keys view →Console
What the ceiling saved you from, as rows.
Calls refused and units refused over a window, the tasks burning down now, every customer by share of spend, and the one number that should be zero.
Open the sample console →Pricing
Free to start. Cheap enough to leave on.
Every plan has every feature. The tiers differ in how many preflight calls a month they include, and in who answers when you write in.
Every feature. Direct line to the founder.
Get ScaleWhat AgentBill does not do
- Stop your run. Preflight answers approved: false and the SDK raises. Your code decides what happens next.
- Read your provider bill. No access to your provider account, no invoice, no dollar estimate. Units are yours to define, and units refused is not money.
- See a call that never asks. No proxy, so an uninstrumented tool or a retry buried in a library is invisible to the ceiling.
- Bind a caller. The ceiling is keyed on (account_id, task_ref). A loop that opens a new task_ref gets a new ceiling.
- Unwind a workflow. Calls are refused, not reversed. Refusing the next call does not undo the ones that already ran.
- Guarantee the TTL fits your job. A reservation not settled inside 60 minutes is reclaimed by a sweeper while your call may still be running.
- Publish a latency SLO. There is none. The free tier is 1,000 calls with no card, enough to measure the added latency on your own workload.
- Replace observability or payments. No tracing, no invoices, no money moved. Polar bills you for AgentBill; nothing bills anyone on your behalf.
- Give your ops team a no-code dashboard. There is a console. The product is an SDK and one endpoint.
- Show a logo wall or a testimonial. Nobody has agreed to be named yet. The install line, the free tier and the response bodies above are what is checkable.
Give one job a ceiling.
Free tier, no card, 1,000 preflight calls a month. If this page took longer to read than the integration takes, we did our job.