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.

Retrieve a commitment detail read model

GET
/scopes/{scopeId}/billing/commitments/{commitmentId}

Retrieves the detail read model for one Commitment, backing the commitment detail page on route load. The payload bundles the commitment itself (type, term, payment, family, region, status, hourly/upfront/ monthly-savings figures in ten-thousandths of the currency unit, utilization/coverage percentages, effective discount fraction, start/expiry timestamps, days-to-expiry and the covered resources with per-resource coverage and on-demand-equivalent cost) plus the trailing 30-day utilization/coverage timeline with per-day committed and on-demand-equivalent amounts in ten-thousandths of the currency unit. Requested data is returned without mutating the resource. Validation: scopeId must be accessible to the caller and commitmentId must identify a commitment within that scope — an unknown or out-of-scope id maps to 404 NOT_FOUND; no body or other inputs. Async & state: Synchronous read; no state change. Status transitions (QUEUED→ACTIVE, ACTIVE→EXPIRING) and renewals arrive as resource.updated SSE frames of kind billing.commitment with a patch of the changed fields. Errors: 401 unauthenticated; 403 caller lacks a billing-capable role on the scope; 404 unknown scopeId or commitmentId; 500 internal read failure. Idempotency/Concurrency: Safe, cacheable; no idempotency key required. The response carries no ETag; purchase and renew do not check If-Match.

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.

commitmentId*string

Identifier of the commitment within the active scope.

Response Body

Commitment detail read model (commitment plus 30-day utilization/coverage timeline).

application/json
  1. response

Detail read model for the commitment detail page (commitment + 30-day timeline).

commitment*

A purchased or queued commitment (Savings Plan / Reserved / Committed-use).

timeline*array<>

Trailing 30-day utilization/coverage timeline.

curl -X GET "https://example.com/scopes/string/billing/commitments/string"
{  "commitment": {    "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"  },  "timeline": [    {      "label": "string",      "date": "2019-08-24T14:15:22Z",      "utilization": 0,      "coverage": 0,      "committed": 0,      "onDemand": 0    }  ]}