Docs / API
Read your spend from your own code
Build your own dashboard, or pull spend into a report you already have. Everything here only reads: nothing changes your budgets, rules or keys.
How to call it
Each read is one GET to the same address as the model endpoint, with your programmable.run key in the Authorization header and the options as query parameters. Answers are JSON, exactly the shapes below. An error answers with an HTTP status and {"error": {"message", "type", "param", "code"}}.
GET https://llm.programmable.run/v1/spend/<read>?<options> Authorization: Bearer <your programmable.run key>
Reading your spend from your own code isn't switched on yet. The address and shapes below are what it will be; every read is marked coming until it answers.
Which key to use
- Use a programmable.run key: one you made on programmable.run, or on Keys and agents in Spend. Give it its own monthly limit.
- Never use your personal account key (the one that starts
aex_). It can do anything your account can, so it must never sit in a dashboard or anywhere else outside your account. - Keep the key on your server, in an environment variable. Never put it in a web page or an app people download.
- A key only ever reads its own account's spend; you don't send your account id. If the key lists its tools, add
spendto them.
Errors
| Status | Codes | Means |
|---|---|---|
| 401 | MISSING_CREDENTIAL, INVALID_API_KEY, PERSONAL_KEY_REFUSED, SIGN_IN_TOKEN_REFUSED | No key, a wrong key, or a key that isn't a programmable.run key. |
| 403 | KEY_RULE_BLOCKED, OTHER_USER_REFUSED, PERMISSION_DENIED | The key may not read (its rules), or the request named someone else. |
| 400 | INVALID_PARAMS | A parameter is missing or out of range; param names it. |
| 429 | RATE_LIMITED | Too many requests with this key; wait for Retry-After. |
| 501 | METHOD_NOT_AVAILABLE | This read isn't switched on yet. |
| 503 | SPEND_READ_UNAVAILABLE, GATEWAY_UNREACHABLE | The platform couldn't answer just now; try again. |
Methods
- GET /v1/spend/usageComingYour spend over a range of UTC days, split the ways you ask for.
- GET /v1/spend/budgetsComingYour budgets, warning and stop levels.
- GET /v1/spend/warningsComingEach time a budget reached its warning level, newest first.
- GET /v1/spend/callsComingEach AI call, newest first, a page at a time. Never prompts or replies.
- GET /v1/spend/outcomesComingFinished work (a programmable.run task, a completed agent task) and the calls that touched it.
Live methods answer today. Coming ones are being switched on across the platform; the shapes shown are the ones Spend itself reads. Days and months are UTC. Money is US dollars.
GET /v1/spend/usage
ComingYour spend over a range of UTC days, split the ways you ask for. This one isn't answering yet; the shape below is what it will return.
| Parameter | About |
|---|---|
start_dateYYYY-MM-DD | First UTC day, included. |
end_dateYYYY-MM-DD | Last UTC day, included. At most 366 days after start_date. |
dimensionscomma list, optional | Any of day, model, provider, lane, agent_id, workflow_id, pipeline, user_id, key_id. Leave it out for one total. |
curl
curl "https://llm.programmable.run/v1/spend/usage?start_date=2026-10-01&end_date=2026-10-29&dimensions=day%2Cmodel" \ -H "Authorization: Bearer $PROGRAMMABLE_RUN_KEY"
fetch (on your server)
const res = await fetch("https://llm.programmable.run/v1/spend/usage?start_date=2026-10-01&end_date=2026-10-29&dimensions=day%2Cmodel", {
headers: { Authorization: `Bearer ${process.env.PROGRAMMABLE_RUN_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message || `HTTP ${res.status}`);Returns
{
"rows": [
{ "day": "2026-10-28", "model": "claude-haiku-4-5", "input_tokens": 120000, "output_tokens": 18000,
"raw_cost_usd": 0.21, "charged_usd": 0.24, "call_count": 64, "error_count": 1 }
],
"totals": { "input_tokens": 120000, "output_tokens": 18000, "raw_cost_usd": 0.21,
"charged_usd": 0.24, "call_count": 64, "error_count": 1 }
}- Only your own spend: a team workspace's report isn't offered here, because it would show other people's spend.
GET /v1/spend/budgets
ComingYour budgets, warning and stop levels. This one isn't answering yet; the shape below is what it will return.
| Parameter | About |
|---|
curl
curl "https://llm.programmable.run/v1/spend/budgets" \ -H "Authorization: Bearer $PROGRAMMABLE_RUN_KEY"
fetch (on your server)
const res = await fetch("https://llm.programmable.run/v1/spend/budgets", {
headers: { Authorization: `Bearer ${process.env.PROGRAMMABLE_RUN_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message || `HTTP ${res.status}`);Returns
{
"guardrails": { "daily": { "all": 20, "agent:<agent id>": 5 }, "monthly": { "all": 300 },
"warn_at_pct": 80, "block_at_pct": 100 },
"updated_at": "2026-10-29T09:12:00Z"
}- paused and paused_at appear once the kill switch is live on the platform.
GET /v1/spend/warnings
ComingEach time a budget reached its warning level, newest first. This one isn't answering yet; the shape below is what it will return.
| Parameter | About |
|---|---|
sinceYYYY-MM-DD, optional | From this UTC day. Defaults to 30 days back. |
curl
curl "https://llm.programmable.run/v1/spend/warnings?since=2026-10-01" \ -H "Authorization: Bearer $PROGRAMMABLE_RUN_KEY"
fetch (on your server)
const res = await fetch("https://llm.programmable.run/v1/spend/warnings?since=2026-10-01", {
headers: { Authorization: `Bearer ${process.env.PROGRAMMABLE_RUN_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message || `HTTP ${res.status}`);Returns
{
"warnings": [
{ "id": "…", "scope": "user", "cap_key": "all", "window": "daily", "period": "2026-10-29",
"warn_pct": 80, "spend_usd": 16.2, "cap_usd": 20, "created_at": "…", "notified_at": "…" }
]
}- Answers 501 (METHOD_NOT_AVAILABLE) until warnings are live on the platform.
GET /v1/spend/calls
ComingEach AI call, newest first, a page at a time. Never prompts or replies. This one isn't answering yet; the shape below is what it will return.
| Parameter | About |
|---|---|
startYYYY-MM-DD | First UTC day, included. |
endYYYY-MM-DD | The day after the last one (not included). At most 366 days. |
limit1-200, optional | Calls per page. Defaults to 50. |
cursorstring, optional | next_cursor from the previous page, unchanged. |
pipelinestring, optional | Only one app. |
agent_idstring, optional | Only one agent. |
curl
curl "https://llm.programmable.run/v1/spend/calls?start=2026-10-01&end=2026-10-30&limit=50" \ -H "Authorization: Bearer $PROGRAMMABLE_RUN_KEY"
fetch (on your server)
const res = await fetch("https://llm.programmable.run/v1/spend/calls?start=2026-10-01&end=2026-10-30&limit=50", {
headers: { Authorization: `Bearer ${process.env.PROGRAMMABLE_RUN_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message || `HTTP ${res.status}`);Returns
{
"calls": [
{ "id": "…", "time": "2026-10-29T10:01:02Z", "pipeline": "chat", "agent_id": null,
"provider": "anthropic", "model": "claude-haiku-4-5", "lane": "managed",
"input_tokens": 1000, "output_tokens": 200, "charged_usd": 0.0123,
"success": true, "error_code": null, "override_rule_id": null }
],
"next_cursor": "…"
}- Answers 501 (METHOD_NOT_AVAILABLE) until the per-call log is live on the platform.
GET /v1/spend/outcomes
ComingFinished work (a programmable.run task, a completed agent task) and the calls that touched it. This one isn't answering yet; the shape below is what it will return.
| Parameter | About |
|---|---|
startYYYY-MM-DD | First UTC day, included. |
endYYYY-MM-DD | The day after the last one (not included). |
limit1-200, optional | Outcomes per page. |
cursorstring, optional | next_cursor from the previous page. |
outcome_kindrun_do | agent_task, optional | Only one kind. |
curl
curl "https://llm.programmable.run/v1/spend/outcomes?start=2026-10-01&end=2026-10-30" \ -H "Authorization: Bearer $PROGRAMMABLE_RUN_KEY"
fetch (on your server)
const res = await fetch("https://llm.programmable.run/v1/spend/outcomes?start=2026-10-01&end=2026-10-30", {
headers: { Authorization: `Bearer ${process.env.PROGRAMMABLE_RUN_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message || `HTTP ${res.status}`);Returns
{
"outcomes": [
{ "outcome_kind": "agent_task", "outcome_id": "…", "time": "2026-10-29T11:00:00Z",
"label": "agent:<agent id>", "attribution_strength": "touched",
"call_ids": ["…"], "call_count": 6, "charged_usd": 0.07 }
],
"summary": { "outcome_count": 12, "linked_call_count": 80,
"linked_charged_usd": 0.92, "cost_per_outcome_usd": 0.08 },
"next_cursor": null
}- "touched" means the calls were seen on the way to the result, not that they caused it.
- Answers 501 (METHOD_NOT_AVAILABLE) until outcomes are live on the platform.