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 spend to them.

Errors

Error codes
StatusCodesMeans
401MISSING_CREDENTIAL, INVALID_API_KEY, PERSONAL_KEY_REFUSED, SIGN_IN_TOKEN_REFUSEDNo key, a wrong key, or a key that isn't a programmable.run key.
403KEY_RULE_BLOCKED, OTHER_USER_REFUSED, PERMISSION_DENIEDThe key may not read (its rules), or the request named someone else.
400INVALID_PARAMSA parameter is missing or out of range; param names it.
429RATE_LIMITEDToo many requests with this key; wait for Retry-After.
501METHOD_NOT_AVAILABLEThis read isn't switched on yet.
503SPEND_READ_UNAVAILABLE, GATEWAY_UNREACHABLEThe platform couldn't answer just now; try again.

Methods

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

Coming

Your 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.

Parameters for get_usage_report
ParameterAbout
start_date
YYYY-MM-DD
First UTC day, included.
end_date
YYYY-MM-DD
Last UTC day, included. At most 366 days after start_date.
dimensions
comma 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

Coming

Your budgets, warning and stop levels. This one isn't answering yet; the shape below is what it will return.

Parameters for get_user_guardrails
ParameterAbout

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

Coming

Each time a budget reached its warning level, newest first. This one isn't answering yet; the shape below is what it will return.

Parameters for list_budget_warnings
ParameterAbout
since
YYYY-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

Coming

Each 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.

Parameters for list_llm_calls
ParameterAbout
start
YYYY-MM-DD
First UTC day, included.
end
YYYY-MM-DD
The day after the last one (not included). At most 366 days.
limit
1-200, optional
Calls per page. Defaults to 50.
cursor
string, optional
next_cursor from the previous page, unchanged.
pipeline
string, optional
Only one app.
agent_id
string, 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

Coming

Finished 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.

Parameters for list_outcomes
ParameterAbout
start
YYYY-MM-DD
First UTC day, included.
end
YYYY-MM-DD
The day after the last one (not included).
limit
1-200, optional
Outcomes per page.
cursor
string, optional
next_cursor from the previous page.
outcome_kind
run_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.