Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
List budgets in the active scope
Returns the Budget records configured in the active scope, as rendered by the Budgets page on route load.
Each budget carries its target scope label, reset period (MONTHLY|QUARTERLY|ANNUAL), the configured
limit and current spent/forecast figures (integers in ten-thousandths of the subscription
currency's unit), its status (ACTIVE or THRESHOLD_BREACHED once spend crosses 100% of the limit), the
configured alert thresholds (percentages such as 50/80/100), the alert channel, the owning team and a
12-point spend history sparkline. Standard q/sort/order/page/pageSize controls apply;
status and period narrow the collection.
Validation: scopeId must be accessible to the caller (404 NOT_FOUND if unknown); status must
be ACTIVE|THRESHOLD_BREACHED and period MONTHLY|QUARTERLY|ANNUAL when supplied; pagination bounds
enforced — violations map to 422 VALIDATION_FAILED.
Async & state: Synchronous read; no state change. Threshold breaches detected by the budget
evaluator are pushed as resource.updated SSE frames (kind billing.budget, patch with status
and spent).
Errors: 401 unauthenticated; 403 caller lacks a billing-capable role on the scope; 404 unknown
scopeId; 422 malformed query parameters; 500 read-model failure.
Idempotency/Concurrency: Safe, cacheable; no idempotency key required.
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
region?stringRestrict the result set to a single region.
^[a-z][a-z0-9-]{1,39}$q?stringFree-text search.
sort?stringField to sort by (entity-specific; defaults to the entity's natural order).
order?stringSort direction.
"asc""asc""desc"page?integer1-based page number.
1 <= value1pageSize?integerItems per page (max 200).
1 <= value <= 20050status?stringFilter budgets by evaluation status.
"ACTIVE""THRESHOLD_BREACHED"period?stringFilter budgets by reset period.
"MONTHLY""QUARTERLY""ANNUAL"Paginated collection of budgets in the active scope.
application/json- response
data*array<>meta*Pagination envelope metadata. List responses are always { data, meta } — never a naked array.
curl -X GET "https://example.com/scopes/string/billing/budgets"{ "data": [ { "id": "string", "name": "string", "scope": "string", "period": "MONTHLY", "limit": 0, "spent": 0, "forecast": 0, "status": "ACTIVE", "thresholds": [ 0 ], "alertChannel": "string", "alertTarget": "string", "owner": "string", "history": [ 0 ], "currency": "USD" } ], "meta": { "page": 1, "pageSize": 1, "total": 0, "hasNext": true }}