Usage
Read a project's credit spend and the per-run itemized cost — usage_summary and the usage_line_items block on a run's status.
IonWarp work draws down credits (1,000 credits = $1) from the workspace's
balance. Every plan includes a monthly allowance; spend past it either stops the
run or bills as metered overage — the workspace's budget setting decides which.
Read one project's spend for a trailing window:
{ "name": "usage_summary", "arguments": { "project_id": "pr_acme", "days": 7 } }days defaults to 7 and is capped at 90. The response is the same rollup the
product's own Usage explorer renders, so the two can never disagree:
by_kind is keyed by the skill id that spent the money, or chat; runs counts
the distinct task runs billed in the window.
Per-run cost, itemized
usage_summary answers "what did this project spend". To attribute ONE run, add
?include=cost to its status read
(GET /api/v1/tasks/{task_id}/status?include=cost) and read usage_line_items.
Nothing is folded into a single opaque number, so a surprising number is always
attributable to a row. Every row carries a category, and there are exactly
five:
| Category | Driven by |
|---|---|
llm | model calls — with input_tokens, output_tokens, and the prompt-cache counters |
api | metered provider calls a run makes (vision and media analysis, search, enrichment) |
storage | bytes an artifact or upload keeps |
compute | sandboxed execution time |
egress | bytes served out |
Each row also carries provider, model, quantity, unit, cost_usd,
credits, and occurred_at.
The allowance, and who can read it
Credits pool at the workspace, not the project or the seat. A plan declares the credits it includes for the period; on a per-seat plan each pooled seat adds bonus credits to that same pool, so adding a teammate raises one number rather than creating a second budget to reconcile.
The remaining-allowance number is not an agent-reachable read. Plans,
balances, and budgets are workspace-billing surfaces behind an owner/admin
session (Settings → Billing in the product) — a PAT reads spend
(usage_summary, usage_line_items), not the ceiling. What an agent gets at
run time is the refusal, and it is complete enough to act on.
Budgets and stops
- Every workspace has ONE effective cap per period — its plan's included allowance, or a custom budget amount when one is set — and autonomous runs stop at it by default. Switching the budget to keep going removes the ceiling entirely; spend past the included allowance then bills as metered overage.
- A run refused for spend returns exactly one code,
spend_cap_reached, whose envelope carriescap_source(included_allowanceorcustom_cap),used,amount, and the remedy. There is no separate plan-allowance or workspace-budget code to branch on: one concept, one code, andcap_sourcenames which ceiling fired. - Unreadable billing evidence admits the run — a veto path never blocks on missing evidence.
- A refusal is always a named, readable code on the task — never a silent stop. See Control Plane for the other spend controls, and Debugging a Run to read one off a run.