Dairo Docs
GuidesAPI referenceDashboard
API referenceBudgets

Get a single budget by scope

Returns one budget with its live usage, addressed by the {scope} path segment: use account for the account-wide budget, or a key/agent budget's scopeId (the API key or agent id it targets).

Endpoint
GET https://api.dairo.app/v1/budgets/{scope}

Returns one budget with its live usage, addressed by the {scope} path segment: use account for the account-wide budget, or a key/agent budget's scopeId (the API key or agent id it targets). The usage fields sendsLast24h, newRecipientsLastHour, and accountHasComplaint are computed at request time from the sends attributed to that scope. Returns 404 when no budget is configured for the scope. Requires the budgets:read scope.

Scope: budgets:read. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

cURL
curl "https://api.dairo.app/v1/budgets/account" \
  -H "Authorization: Bearer $DAIRO_API_KEY"

Response

200 Success. Body: application/json, BudgetResponse.

FieldTypeRequiredDescription
budgetBudgetyes
200
{
  "budget": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "scope": "account",
    "scopeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "enabled": true,
    "limits": {
      "maxSendsPerDay": null,
      "maxNewRecipientsPerHour": null,
      "hardStopOnComplaint": true,
      "maxSpendPerDayCents": null
    },
    "usage": {
      "sendsLast24h": 0,
      "newRecipientsLastHour": 0,
      "accountHasComplaint": true
    },
    "createdAt": "2026-10-19T09:30:00Z",
    "updatedAt": "2026-10-19T09:30:00Z"
  }
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.

StatusMeaning
400The request is malformed or a value is invalid (invalid_request, invalid_domain, idempotency_key_mismatch).
401The API key is missing or invalid.
403The key lacks the scope this endpoint needs (scope_missing) or may not do this (not_permitted).
404No such resource in this account (resource_not_found).
422The request is well-formed but a field failed validation (validation_failed).
429Rate limit, plan limit, budget or spend cap reached (rate_limited, plan_limit_reached, budget_exceeded, spend_cap_reached).
500An unexpected error; retry with backoff, then contact support (internal_error).

Set or replace a budget

Creates or replaces the budget for a scope: account (omit scopeId), or key/agent (each requires a scopeId you own — an API key id (a UUID) for key, or an agent's id or portable agt_… id for agent).

Delete a budget for a scope

Permanently removes the budget for the {scope} path segment — account, or a key/agent budget's scopeId — and returns 204 No Content with an empty body.

On this page

RequestResponseErrors