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 and query commitments in the active scope

GET
/scopes/{scopeId}/billing/commitments

Returns the Commitment records (Savings Plans, Reserved Instances, Committed-use Discounts) in the active scope, as rendered by the Commitments page on route load. This single operation also serves the UI's search/filter/sort/pagination controls (collapsed billing.commitment.search_filter_sort): free-text q, a type filter matching the UI's type counter chips (SAVINGS_PLAN|RESERVED), a status filter (ACTIVE|EXPIRING|EXPIRED|QUEUED|PENDING_ACTIVATION|REJECTED) and standard sort/order/page/pageSize. Each commitment carries its term (1yr|3yr), payment option, family, region, hourly committed rate / upfront paid / realized monthly savings (integers in ten-thousandths of the currency unit), utilization and coverage percentages, effective discount fraction, start/expiry timestamps, daysToExpiry and the covered resources breakdown. No resource state is mutated. Validation: scopeId must be accessible (404 NOT_FOUND if unknown); type must be one of SAVINGS_PLAN|RESERVED and status one of ACTIVE|EXPIRING|EXPIRED|QUEUED|PENDING_ACTIVATION|REJECTED when supplied; pagination bounds enforced — violations map to 422 VALIDATION_FAILED. Async & state: Synchronous read; no state change. QUEUED commitments transitioning to ACTIVE after purchase settlement are pushed as resource.updated SSE frames (kind billing.commitment). 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
type?string

Filter commitments by commitment type (UI type counter chips).

Value in"SAVINGS_PLAN""RESERVED"
status?string

Filter commitments by lifecycle status.

Value in"ACTIVE""EXPIRING""EXPIRED""QUEUED""PENDING_ACTIVATION""REJECTED"

Response Body

Paginated collection of commitments 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/commitments"
{  "data": [    {      "id": "string",      "name": "string",      "type": "SAVINGS_PLAN",      "term": "1yr",      "payment": "ALL_UPFRONT",      "scope": "string",      "family": "string",      "region": "string",      "status": "ACTIVE",      "hourly": 0,      "upfront": 0,      "upfrontTax": 0,      "upfrontGross": 0,      "utilization": 0,      "coverage": 0,      "monthlySavings": 0,      "discount": 0,      "startedAt": "2019-08-24T14:15:22Z",      "expiresAt": "2019-08-24T14:15:22Z",      "daysToExpiry": 0,      "coveredResources": [        {          "id": "string",          "hrefSeg": "string",          "name": "string",          "kind": "string",          "coverage": 0,          "onDemand": 0        }      ],      "renewedFromId": "string",      "renewalId": "string"    }  ],  "meta": {    "page": 1,    "pageSize": 1,    "total": 0,    "hasNext": true  }}