Questions
Answers checked against the source, not the marketing. Where the product does not do something, it says so.
What does a job count?
Dollars, tokens or units, chosen when the job opens and fixed from then on. Open it in dollars with task_ceiling_usd on wrap() or on the preflight that opens it, or with ceiling_usd from the console or PUT /tasks/:task_ref/ceiling, and AgentBill prices each call itself: the public list price of the tokens your provider reported, from a dated snapshot of the LiteLLM price table. Before a call it reserves your estimated_usd if you pass one, otherwise the median of the job's last 20 priced calls (their largest once the job is at 80% of its ceiling, counting calls still in flight), or $0.10 before it has one. A call it cannot price is charged its reservation, never $0. In tokens, which is what wrap() uses unless you open the job in dollars, the ceiling is the tokens your provider reported. In units, the default for a preflight that names no unit, the number is an integer you define and pass, and AgentBill never converts it to money. Every dollar figure is an estimate at list price, not your invoice.
Can I see what each client cost me?
Yes. Pass customer_id on wrap() or on each record, and the console's monthly report gives one line per customer for the calendar month (UTC), broken down by agent and model, as a CSV or a printable page. The figure is the list-price estimate stored with each priced call, whatever the job counts, so it is what you bill from, not what your provider will invoice. A call with no list price is counted as unpriced, never added as $0.
What actually refuses a call, and what happens after it does?
Five things, and each one names itself. ceiling_exceeded means this one call's estimate is over the per-call ceiling. task_ceiling_exceeded means used plus reserved plus this estimate would cross the ceiling on that task_ref. budget_exhausted means that customer's own limit. free_tier_exceeded and plan_limit_exceeded mean our monthly quota ran out, not yours. All five come back as a 200 with approved false, carrying the numbers the decision was made on, and preflight then raises for the three that are your spend rule so a check you forgot to read cannot be silently ignored, and returns the result with an upgrade_url for the two that are ours. What happens next is your code's decision: retry with a smaller estimate, drop to a cheaper model, return what you have, or stop. We are not in your process and cannot end it.
Does AgentBill count my tool calls and GPU time automatically?
No. Tool calls and GPU time are counted only when your code says so. A job's numbers move when you call preflight, record an event, or record a step, and they count against a job's ceiling only when the call carries the same task_ref. So a tool, a GPU run or a vector search counts if you instrument it with that task_ref, and does not exist to us if you do not. Model calls are the one thing counted for you, and only through a client you wrapped with wrap(): OpenAI, Anthropic and Gemini calls through their create methods, recorded from the usage the provider returned to your process. An unwrapped call is not counted. Nothing sits in your traffic to watch it, which is the trade: one number for a whole job across every provider, because your code, or wrap(), reported what each step used.
Does AgentBill see my provider bill?
No. It never has access to your OpenAI, Anthropic or cloud account, and it does not read or reconcile against your invoice. It knows what your code told it a call was worth or, through wrap(), the token counts on the response your own process received. The dollar figure beside those tokens is an estimate at public list price, never a reading of your bill: list price, your invoice may differ.
How is a task budget different from a monthly spend cap?
A monthly cap resets on a calendar. A task budget is attached to a task_ref, so every call in one job draws down one ceiling regardless of which provider it goes to, and the ceiling is consulted before each call rather than totalled at the end of a period. A budget that resets tomorrow does not stop the loop that is running tonight.
Can I put a budget on one agent?
No, and it is deliberate rather than missing. agent_id is a label: it is stored on every task, step and refusal, and you can filter tasks and decisions by it, but nothing is capped by it. Ceilings hang off a task_ref, off a customer, or off a single call. Two different agents that pass the same task_ref share one ceiling, which is usually what you wanted, because the job is the thing that costs money and the agent is whichever process happened to pick it up.
What happens if a job dies holding a reservation?
Preflight reserves the estimate it approves, so two calls racing cannot both be told there is room for one. A reservation that is never settled expires after 60 minutes and is swept back to the budget every five minutes. Nothing is held forever because a process crashed, and nothing is released early because a process was slow.
What happens when I reach the free tier's 1,000 calls?
Preflight starts answering approved: false with reason free_tier_exceeded (plan_limit_exceeded on a paid plan) and an upgrade_url. Unlike a ceiling refusal, the SDK returns that answer instead of raising, on purpose, so our quota running out does not crash your agent: check result.approved, and your code decides what happens next. Nothing is billed, a refused call reserves nothing and is not counted, and the counter is checked and incremented in one statement so calls arriving together cannot all read the same number and all pass.
Which features are on which plan?
All of them, on all of them. Nothing in the code gates a feature by plan: the only thing a plan changes is how many preflight calls a month it includes, and who answers when you write in. Tiers here sell headroom, not capability.
Does AgentBill sit in my request path?
No. It is an endpoint your code calls before it calls a provider, not a gateway your traffic routes through. Nothing to point your base URL at, nothing new that can be down between you and OpenAI, and no third party holding your provider keys. If AgentBill is unreachable your code decides what to do, which is a decision a proxy would have taken away from you.
What can I do if a key leaks?
Revoke it, and it stops authenticating on the next request rather than at the end of a billing period. You can also rotate it, which issues a new key and keeps the old one working for an hour (or as long as you ask, up to a day) so a deploy is not an outage; set an expiry when you generate it; and hold several labelled keys per account. Keys are rate limited, and a key used from a new address emails you.