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 billing summary read models for the active scope

GET
/scopes/{scopeId}/billing/summary

Returns the Billing Summary read model(s) for the active scope, backing the Billing summary page on route load. Each summary entry carries the right-rail metrics (all-time spend, month-to-date, projected monthly, hourly run rate, available credits, last-month total — all integers in ten-thousandths of the subscription currency's unit — plus the signed forecastDelta percentage vs last month) and the active service cards (per-service resource count, month-to-date spend and signed trend percentage). The collection normally contains a single row for the requested scope but is shaped as a standard paginated collection. Validation: scopeId must reference a tenant/subscription/project scope the caller can access — unknown scope maps to 404 NOT_FOUND; pagination parameters must be within bounds, else 422 VALIDATION_FAILED. No other inputs. Async & state: Synchronous read; no state change. The summary is recomputed server-side from the cost read model as ingestion progresses; no SSE frames are tied to this endpoint. Errors: 401 unauthenticated; 403 caller lacks a billing-capable role (owner|admin|contributor|reader|billing) 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

Response Body

Paginated collection of billing summary read models for the 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/summary"
{  "data": [    {      "currency": "USD",      "metrics": {        "allTime": 0,        "monthToDate": 0,        "projectedMonthly": 0,        "hourlyRate": 0,        "availableCredits": 0,        "lastMonth": 0,        "forecastDelta": 0      },      "activeServices": [        {          "id": "string",          "name": "string",          "resources": 0,          "monthToDate": 0,          "trend": 0,          "color": "string"        }      ],      "coverage": "subscription"    }  ],  "meta": {    "page": 1,    "pageSize": 1,    "total": 0,    "hasNext": true  }}