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
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.
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 <= 20050type?stringFilter commitments by commitment type (UI type counter chips).
"SAVINGS_PLAN""RESERVED"status?stringFilter commitments by lifecycle status.
"ACTIVE""EXPIRING""EXPIRED""QUEUED""PENDING_ACTIVATION""REJECTED"Paginated collection of commitments 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/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 }}