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

FieldTypeDescription
objectstringAlways "usage_report".
fromstringFirst day included (YYYY-MM-DD, UTC).
tostringLast day included.
group_bystringThe grouping used.
total_usdnumberSum of every row.
rowsobject[]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.
Usage report
{
  "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

FieldTypeDescription
objectstringAlways "credit_balance".
includedobjectThis period’s included allowance: granted_usd, used_usd and resets_at.
prepaid_usdnumberPrepaid credits. They never expire.
overage_this_period_usdnumberMetered usage beyond the allowance and prepaid credits, if overage is on.
auto_rechargeobjectenabled, 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.

Credit balance
{
  "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

FieldTypeDescription
idstringUnique id, prefixed bud_.
objectstringAlways "budget".
scopeobjectWhat it caps: kind (workspace, project, factory, workflow, member or agent) and id (null for the workspace).
periodenumrun, day or month. A workflow’s Budget per run shows here as a workflow budget with period run.
limit_usdnumberThe cap.
spent_usdnumberSpend in the current period. For run budgets, the highest spend of any run in progress.
alert_atnumber[]Percentages that send an alert, e.g. [50, 80, 100].
actionenumWhat 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.

Budget
{
  "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

GET 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

from string Required

First day, YYYY-MM-DD (UTC).

to string Required

Last day, inclusive. At most 366 days after from.

group_by enum Optional

How to group rows.

Default day

One of project factory workflow agent model member machine day

billed_to enum Optional

Only spend billed this way. Omit for all three.

One of duun provider owned

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}")
Response
{
  "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_request with param: "to" when to is before from or the range is longer than 366 days.
  • 403 permission_denied with code member_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

GET 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

GET 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_kind enum Optional

Only budgets on this kind of scope.

One of workspace project factory workflow member agent

scope_id string Optional

Only budgets on this object, e.g. fac_platform.

limit integer Optional

1–100.

Default 20

cursor string Optional

next_cursor from 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)
Response
{
  "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.

    Type to search the docs, help center and blog.