Budgets and usage
Read what a session cost, follow cost on its event stream, and cap its spend.
Every session has a cost, and you decide how high it can go. Set a credit cap when you open the session. The agent plans inside it, and when the cap is reached it wraps up with what it has made. Afterwards, one call tells you what the session spent.
What a session is billed for
Section titled “What a session is billed for”A session spends the same credits as POST /v1/generations, on two things:
- each generation the agent starts, or that you start as a generate run, at that model’s rate;
- the agent’s own work: planning, calling tools, checking results and writing replies.
A session has no fee of its own. The agent’s work can cost more than the generations, so a brief that takes many back-and-forth steps costs more than one that is clear from the start. GET /v1/models lists the live credits for each model (see Models).
Cap a session
Section titled “Cap a session”Set cost_policy on POST /v1/sessions:
curl -s -X POST https://agents.lumalabs.ai/v1/sessions \ -H "Authorization: Bearer $SESSION_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: campaign-1" \ -d '{ "scope_id": "'"$WORKSPACE_ID"'", "cost_policy": { "max_total_credits": 500 } }'import jsonimport osimport urllib.parseimport urllib.request
BASE = "https://agents.lumalabs.ai/v1"
def post(path, body, token, headers=None): request = urllib.request.Request( BASE + path, method="POST", data=json.dumps(body).encode(), headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json", **(headers or {})}, ) with urllib.request.urlopen(request) as response: return json.load(response)
def get(path, token): request = urllib.request.Request(BASE + path, headers={"Authorization": f"Bearer {token}"}) with urllib.request.urlopen(request) as response: return json.load(response)
session = post( "/sessions", {"scope_id": workspace_id, "cost_policy": {"max_total_credits": 500}}, session_token, headers={"Idempotency-Key": "campaign-1"},)const BASE = "https://agents.lumalabs.ai/v1";
async function post( path: string, body: unknown, token: string, headers: Record<string, string> = {},) { const response = await fetch(BASE + path, { method: "POST", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...headers, }, body: JSON.stringify(body), }); if (!response.ok) throw new Error(`${response.status} ${await response.text()}`); return response.json();}
async function get(path: string, token: string) { const response = await fetch(BASE + path, { headers: { Authorization: `Bearer ${token}` }, }); if (!response.ok) throw new Error(`${response.status} ${await response.text()}`); return response.json();}
const session = await post( "/sessions", { scope_id: workspaceId, cost_policy: { max_total_credits: 500 } }, sessionToken, { "Idempotency-Key": "campaign-1" },);max_total_credits is checked before every generation the agent starts, against that generation’s estimate. The agent’s own work is held to the same cap. The cap covers the session and any sessions it starts, such as an app run.
A cost_policy only tightens. A value above a limit your account already has doesn’t raise that limit.
What happens at the cap
Section titled “What happens at the cap”- 1Check
job.startedEach generation is admitted on its estimate - 2RefuseOne that would cross the cap is not started
- 3Wrap upThe agent is told, and finishes with what it has
- 4Stop
budget_reachedThe turn ends; the session stays open
Reaching the cap mid-turn isn’t an HTTP error. The turn ends with stop_reason budget_reached, or end_turn if work it started earlier was still running. The session stays active, so your user can send another message, though the agent can’t start new generations past the cap.
A request whose estimate would cross the cap, such as a new generate run, is refused with 402 SESSION.BUDGET_EXHAUSTED. The same 402 comes back when your account balance or your API key’s period cap runs out. 402 always means money.
Read what a session spent
Section titled “Read what a session spent”curl -s "https://agents.lumalabs.ai/v1/sessions/$SESSION_ID/usage" \ -H "Authorization: Bearer $SESSION_TOKEN"usage = get(f"/sessions/{session_id}/usage", session_token)print(usage["total_credits"])const usage = await get(`/sessions/${sessionId}/usage`, sessionToken);console.log(usage.total_credits);{ "session_id": "0c6f3c1e-8a52-4d7b-9a43-2f1e6b9d5a10", "total_credits": 374, "unresolved_event_count": 0, "stages": [ { "stage": "unattributed", "credits": 104, "event_count": 3, "llm_call_count": 0, "generation_count": 2, "input_tokens": 0, "output_tokens": 0, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0 }, { "stage": "session", "credits": 270, "event_count": 2, "llm_call_count": 2, "generation_count": 0, "input_tokens": 42500, "output_tokens": 2300, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0 } ], "jobs": [ { "job_id": "apijob_4f1c9a2e7b", "model": "uni-1", "credits": 14, "credits_estimated": false }, { "job_id": "apijob_8d03e6b51c", "model": "ray-3.2", "credits": 90, "credits_estimated": true } ]}total_creditsis everything the session and the sessions it started have spent, for its whole life. Don’t add a child session’s figure to its parent’s.stagessplits the same total by stage, with the model calls and tokens behind each.jobshas one line per generation.credits_estimated: truemarks one still running, counted at its estimate until it settles.total_creditsminus the sum ofjobs[].creditsis the agent’s own work, plus small charges such as a content check.unresolved_event_countabove0means some cost isn’t priced yet. Read again later.
Read it with a session token for the same user_id (and tenant_id, if any) that opened the session.
Three cost recipes
Section titled “Three cost recipes”What did this end user spend this month?
Section titled “What did this end user spend this month?”Tag each session with your id for the end user when you open it: "metadata": { "end_user": "advertiser-4417" }. Then group your settled spend by that tag, using your API key:
curl -s "https://agents.lumalabs.ai/v1/usage?group_by=metadata&metadata_key=end_user&metadata.end_user=advertiser-4417&start=2026-11-01T00:00:00Z" \ -H "Authorization: Bearer $LUMA_AGENTS_API_KEY" \ | jq '.groups[] | select(.value == "advertiser-4417") | .total_credits'query = urllib.parse.urlencode({ "group_by": "metadata", "metadata_key": "end_user", "metadata.end_user": "advertiser-4417", "start": "2026-11-01T00:00:00Z",})report = get(f"/usage?{query}", os.environ["LUMA_AGENTS_API_KEY"])for group in report["groups"]: if group["value"] == "advertiser-4417": print(group["total_credits"])const query = new URLSearchParams({ group_by: "metadata", metadata_key: "end_user", "metadata.end_user": "advertiser-4417", start: "2026-11-01T00:00:00Z",});const report = await get(`/usage?${query}`, process.env.LUMA_AGENTS_API_KEY!);for (const group of report.groups) { if (group.value === "advertiser-4417") console.log(group.total_credits);}This counts settled charges only. It misses work still running and sessions opened without the tag. For a figure that includes running work, add up total_credits from each session you recorded for that user.
What did the agent’s work cost in this session?
Section titled “What did the agent’s work cost in this session?”curl -s "https://agents.lumalabs.ai/v1/sessions/$SESSION_ID/usage" \ -H "Authorization: Bearer $SESSION_TOKEN" \ | jq '{ total: .total_credits, generations: ([.jobs[].credits] | add // 0) } | . + { agent: (.total - .generations) }'usage = get(f"/sessions/{session_id}/usage", session_token)total = usage["total_credits"]generations = sum(job["credits"] for job in usage["jobs"])print({"total": total, "generations": generations, "agent": total - generations})const split = await get(`/sessions/${sessionId}/usage`, sessionToken);const total: number = split.total_credits;const generations = (split.jobs as { credits: number }[]).reduce( (sum, job) => sum + job.credits, 0,);console.log({ total, generations, agent: total - generations });Show a running cost in your UI
Section titled “Show a running cost in your UI”Read cost off the stream as it happens:
| Event | Field | Use it to |
|---|---|---|
job.started | estimated_credits | Show what a generation is expected to cost |
job.completed | credits_charged, credits_estimated | Update that generation’s line. Mark the total approximate while any line is an estimate |
job.failed | credits_charged | Usually 0 |
session.status_idle | Refresh the full total from GET …/usage |
Keep the latest figure per job_id. No event carries the cost of the agent’s own work, so the idle refresh is what brings the total up to date.
Details
Section titled “Details”cost_policyalso takesper_stage_caps, up to 32 entries. Stage names are Luma’s own labels.- Your API key can also have a spending cap per billing period. If 80% or more of it is spent when a session opens,
session.budget_warningreports what is left. - Three reads count differently.
GET /v1/usagecounts settled charges only.GET /v1/creditsis your balance less credits held for running work. A session’susageadds estimates for running work. Reconcile and invoice on settled figures, after estimates clear. GET /v1/sessions/$SESSION_ID/jobs/{job_id}returns a generation’s settledcredits_chargedonce it settles.job.completedisn’t sent again.- Every figure is in credits. To convert to dollars, see Pricing.
- Generate runs: direct generations that spend the same budget.
- Pricing: per-model rates.
- Workspaces and access: keep each customer’s work and spend apart.