--- title: Budgets and usage | Luma Agents description: 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 A session spends the same credits as [`POST /v1/generations`](/guides/pricing/index.md), on two things: - each generation the agent starts, or that you start as a [generate run](/agents/generations/index.md), 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](/guides/model/index.md)). ## Cap a session Set `cost_policy` on `POST /v1/sessions`: - [cURL](#tab-panel-0-0) - [Python](#tab-panel-0-1) - [TypeScript](#tab-panel-0-2) ```bash 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 } }' ``` ```python import json import os import urllib.parse import 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"}, ) ``` ```typescript const BASE = "https://agents.lumalabs.ai/v1"; async function post( path: string, body: unknown, token: string, headers: Record = {}, ) { 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 1. 1**Check**`job.started`Each generation is admitted on its estimate 2. 2**Refuse**One that would cross the cap is not started 3. 3**Wrap up**The agent is told, and finishes with what it has 4. 4**Stop**`budget_reached`The 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. Settled spend can end slightly above the cap. Generations are admitted on their estimates, and the final charge can be higher or lower. ## Read what a session spent - [cURL](#tab-panel-1-0) - [Python](#tab-panel-1-1) - [TypeScript](#tab-panel-1-2) ```bash curl -s "https://agents.lumalabs.ai/v1/sessions/$SESSION_ID/usage" \ -H "Authorization: Bearer $SESSION_TOKEN" ``` ```python usage = get(f"/sessions/{session_id}/usage", session_token) print(usage["total_credits"]) ``` ```typescript const usage = await get(`/sessions/${sessionId}/usage`, sessionToken); console.log(usage.total_credits); ``` ```json { "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_credits` is 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. - `stages` splits the same total by stage, with the model calls and tokens behind each. - `jobs` has one line per generation. `credits_estimated: true` marks one still running, counted at its estimate until it settles. - `total_credits` minus the sum of `jobs[].credits` is the agent’s own work, plus small charges such as a content check. - `unresolved_event_count` above `0` means 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 ### 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](#tab-panel-2-0) - [Python](#tab-panel-2-1) - [TypeScript](#tab-panel-2-2) ```bash 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' ``` ```python 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"]) ``` ```typescript 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? - [cURL](#tab-panel-3-0) - [Python](#tab-panel-3-1) - [TypeScript](#tab-panel-3-2) ```bash 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) }' ``` ```python 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}) ``` ```typescript 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 Read cost off the [stream](/agents/streaming/index.md) 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 - `cost_policy` also takes `per_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_warning` reports what is left. - Three reads count differently. `GET /v1/usage` counts settled charges only. `GET /v1/credits` is your balance less credits held for running work. A session’s `usage` adds 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 settled `credits_charged` once it settles. `job.completed` isn’t sent again. - Every figure is in credits. To convert to dollars, see [Pricing](/guides/pricing/index.md). ## Next - [Generate runs](/agents/generations/index.md): direct generations that spend the same budget. - [Pricing](/guides/pricing/index.md): per-model rates. - [Workspaces and access](/agents/workspaces/index.md): keep each customer’s work and spend apart.