List spend and send budgets

Returns every budget configured for the active organization, each with its resolved limits and live windowed usage.

Endpoint

GET https://api.dairo.app/v1/budgets

Returns every budget configured for the active organization, each with its resolved limits and live windowed usage. The usage object reports sendsLast24h (recipient-denominated sends in the trailing 24 hours), newRecipientsLastHour (recipients addressed in the trailing hour), and accountHasComplaint (whether any complaint has been recorded, which is what drives hardStopOnComplaint). Budgets are returned in a single unpaginated data array ordered by scope; there is no cursor. 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" \
  -H "Authorization: Bearer $DAIRO_API_KEY"

Response

200 Success. Body: application/json, BudgetListResponse.

Field	Type	Required
`object`	`"list"`	yes
`data`	array of Budget	yes
`pagination`	Pagination	yes

200

{
  "object": "list",
  "data": [
    {
      "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"
    }
  ],
  "pagination": {
    "nextCursor": "string",
    "hasMore": true
  }
}

Errors

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

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

List spend and send budgets

Request

Response

Errors

On this page