Usage and budgets
Read spend grouped by project, factory, workflow, agent, model, member, machine or day, your credit balance and auto-recharge, and the budgets that cap runs.
On this page
These endpoints are read-only. They return the same numbers as Settings → Billing & usage: the usage explorer, the credit balance and the budgets table. Use them to feed spend into your own dashboards or finance tools. All three need the usage:read scope.
Amounts are US dollars. Spend that Duun doesn’t bill, such as model calls on your own provider keys or work on machines you own, is reported with billed_to set to provider or owned, so you can see the total cost without it counting against your credits.
To change budgets, plans or auto-recharge, use the app. See Limits and budgets and Budgets and alerts.
The usage report object
| Field | Type | Description |
|---|---|---|
object | string | Always "usage_report". |
from | string | First day included (YYYY-MM-DD, UTC). |
to | string | Last day included. |
group_by | string | The grouping used. |
total_usd | number | Sum of every row. |
rows | object[] | One row per group: key (an id, model name or date), label (display name), amount_usd, runs (runs that contributed) and billed_to (duun, provider or owned). A group with spend under more than one billed_to has one row for each. |
{
"object": "usage_report",
"from": "2026-11-01",
"to": "2026-11-15",
"group_by": "factory",
"total_usd": 742.18,
"rows": [
{ "key": "fac_platform", "label": "Platform", "amount_usd": 412.6, "runs": 186, "billed_to": "duun" },
{ "key": "fac_platform", "label": "Platform", "amount_usd": 96.0, "runs": 41, "billed_to": "provider" },
{ "key": "fac_growth", "label": "Growth", "amount_usd": 180.22, "runs": 77, "billed_to": "duun" },
{ "key": "fac_mobile", "label": "Mobile", "amount_usd": 53.36, "runs": 9, "billed_to": "owned" }
]
}provider and owned amounts are estimates Duun records for visibility. Your provider’s invoice is the source of truth for those.
The credit balance object
| Field | Type | Description |
|---|---|---|
object | string | Always "credit_balance". |
included | object | This period’s included allowance: granted_usd, used_usd and resets_at. |
prepaid_usd | number | Prepaid credits. They never expire. |
overage_this_period_usd | number | Metered usage beyond the allowance and prepaid credits, if overage is on. |
auto_recharge | object | enabled, below_usd (buy when the balance drops under this), amount_usd (how much to buy) and monthly_cap_usd (null for no cap). |
Usage draws from the included allowance first, then prepaid credits, then metered overage if it’s enabled. Otherwise runs pause.
{
"object": "credit_balance",
"included": {
"granted_usd": 600,
"used_usd": 412.6,
"resets_at": "2026-12-01T00:00:00Z"
},
"prepaid_usd": 250,
"overage_this_period_usd": 0,
"auto_recharge": {
"enabled": true,
"below_usd": 50,
"amount_usd": 200,
"monthly_cap_usd": 1000
}
}The figures in these examples are illustrative.
The budget object
| Field | Type | Description |
|---|---|---|
id | string | Unique id, prefixed bud_. |
object | string | Always "budget". |
scope | object | What it caps: kind (workspace, project, factory, workflow, member or agent) and id (null for the workspace). |
period | enum | run, day or month. A workflow’s Budget per run shows here as a workflow budget with period run. |
limit_usd | number | The cap. |
spent_usd | number | Spend in the current period. For run budgets, the highest spend of any run in progress. |
alert_at | number[] | Percentages that send an alert, e.g. [50, 80, 100]. |
action | enum | What happens at 100%: notify (alert only), pause (new runs queue, running runs pause at their next step boundary) or ask (pause and post a budget ask for each run). |
The lowest applicable limit always wins. A run is capped by whichever is reached first: its own limit, its step’s, its workflow’s, its agent’s, its factory’s, its project’s, the member’s, the workspace’s, or the remaining balance.
{
"id": "bud_platformday",
"object": "budget",
"scope": { "kind": "factory", "id": "fac_platform" },
"period": "day",
"limit_usd": 120,
"spent_usd": 84.3,
"alert_at": [50, 80, 100],
"action": "pause"
}Endpoints
Retrieve usage
https://api.duun.ai/v1/usage Returns spend for a date range, grouped one way. Data is usually current to within a few minutes; the current day can still change. Needs usage:read.
Query parameters
-
fromstring Required -
First day,
YYYY-MM-DD(UTC). -
tostring Required -
Last day, inclusive. At most 366 days after
from. -
group_byenum Optional -
How to group rows.
-
billed_toenum Optional -
Only spend billed this way. Omit for all three.
curl "https://api.duun.ai/v1/usage?from=2026-11-01&to=2026-11-15&group_by=factory" \
-H "Authorization: Bearer $DUUN_API_KEY"import Duun from "@duun/sdk";
const duun = new Duun({ apiKey: process.env.DUUN_API_KEY });
const report = await duun.usage.retrieve({ from: "2026-11-01", to: "2026-11-15", group_by: "factory" });
for (const row of report.rows) {
console.log(row.label.padEnd(12), row.billed_to.padEnd(9), `$${row.amount_usd.toFixed(2)}`);
}from duun import Duun
client = Duun()
report = client.usage.retrieve(from_="2026-11-01", to="2026-11-15", group_by="factory")
for row in report.rows:
print(f"{row.label:<12} {row.billed_to:<9} ${row.amount_usd:.2f}"){
"object": "usage_report",
"from": "2026-11-01",
"to": "2026-11-15",
"group_by": "factory",
"total_usd": 742.18,
"rows": [
{ "key": "fac_platform", "label": "Platform", "amount_usd": 412.6, "runs": 186, "billed_to": "duun" },
{ "key": "fac_platform", "label": "Platform", "amount_usd": 96.0, "runs": 41, "billed_to": "provider" },
{ "key": "fac_growth", "label": "Growth", "amount_usd": 180.22, "runs": 77, "billed_to": "duun" },
{ "key": "fac_mobile", "label": "Mobile", "amount_usd": 53.36, "runs": 9, "billed_to": "owned" }
]
}In Python the from parameter is from_, because from is a reserved word.
Errors worth handling:
400 invalid_requestwithparam: "to"whentois beforefromor the range is longer than 366 days.403 permission_deniedwith codemember_usage_only: the key belongs to a context that can only see its own usage. Workspace API keys see all usage.
Retrieve the credit balance
https://api.duun.ai/v1/usage/credits Returns the included allowance, prepaid credits, overage and auto-recharge settings. Needs usage:read.
curl https://api.duun.ai/v1/usage/credits \
-H "Authorization: Bearer $DUUN_API_KEY"const credits = await duun.usage.credits();
const left = credits.included.granted_usd - credits.included.used_usd + credits.prepaid_usd;
if (left < 100) console.warn(`Only $${left.toFixed(2)} of credit left`);credits = client.usage.credits()
left = credits.included.granted_usd - credits.included.used_usd + credits.prepaid_usd
if left < 100:
print(f"Only ${left:.2f} of credit left")The response is a credit balance object.
List budgets
https://api.duun.ai/v1/budgets Returns every budget in the workspace, including per-run caps from workflow Limits and day or month caps from factory Guardrails. Needs usage:read.
Query parameters
-
scope_kindenum Optional -
Only budgets on this kind of scope.
-
scope_idstring Optional -
Only budgets on this object, e.g.
fac_platform. -
limitinteger Optional -
1–100.
-
cursorstring Optional -
next_cursorfrom the previous page.
curl "https://api.duun.ai/v1/budgets?scope_id=fac_platform" \
-H "Authorization: Bearer $DUUN_API_KEY"for await (const b of duun.budgets.list({ scope_id: "fac_platform" })) {
const pct = Math.round((b.spent_usd / b.limit_usd) * 100);
console.log(b.scope.kind, b.period, `${pct}%`, b.action);
}for b in client.budgets.list(scope_id="fac_platform"):
pct = round(b.spent_usd / b.limit_usd * 100)
print(b.scope.kind, b.period, f"{pct}%", b.action){
"object": "list",
"data": [
{
"id": "bud_platformday",
"object": "budget",
"scope": { "kind": "factory", "id": "fac_platform" },
"period": "day",
"limit_usd": 120,
"spent_usd": 84.3,
"alert_at": [50, 80, 100],
"action": "pause"
},
{
"id": "bud_platformmonth",
"object": "budget",
"scope": { "kind": "factory", "id": "fac_platform" },
"period": "month",
"limit_usd": 2000,
"spent_usd": 508.6,
"alert_at": [50, 80, 100],
"action": "ask"
}
],
"has_more": false,
"next_cursor": null
}To act when spend crosses a threshold instead of polling, subscribe a webhook endpoint to budget.threshold.
Related
- Limits and budgets
- Credits and auto-recharge and A run was paused by a budget in the help center