Billing & FinOps

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

GET
/scopes/{scopeId}/billing/budgets

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.

Authorization

bearerToken
headerAuthorizationBearer <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.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

Query Parameters

region?string

Restrict the result set to a single region.

Match^[a-z][a-z0-9-]{1,39}$
q?string

Free-text search.

sort?string

Field to sort by (entity-specific; defaults to the entity's natural order).

order?string

Sort direction.

Default"asc"
Value in"asc""desc"
page?integer

1-based page number.

Range1 <= value
Default1
pageSize?integer

Items per page (max 200).

Range1 <= value <= 200
Default50
status?string

Filter budgets by evaluation status.

Value in"ACTIVE""THRESHOLD_BREACHED"
period?string

Filter budgets by reset period.

Value in"MONTHLY""QUARTERLY""ANNUAL"

Response Body

Paginated collection of budgets in the active scope.

application/json
  1. 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  }}