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 cost report datasets for Cost Explorer

GET
/scopes/{scopeId}/billing/cost-reports

Returns Cost Report read models for the active scope, backing the Cost explorer page on route load. A cost report is a time-bucketed, stacked spend dataset shaped by three query dimensions visible in the UI control bar: groupBy (service|project|region|tag), period (7d|30d|90d|mtd) and granularity (daily|monthly). Each report carries the resolved dimensions (id/name/color), the bucketed series (per-bucket label, ISO date and per-series values in ten-thousandths of the currency unit keyed by series id), the period total and previous-period total (integers in ten-thousandths of the currency unit), and a per-dimension breakdown with current/previous amounts and a sparkline. No resource state is mutated. Validation: scopeId must be accessible (404 NOT_FOUND if unknown); groupBy, period and granularity must be valid enum members when supplied (defaults: service/30d/daily); pagination bounds enforced — violations map to 422 VALIDATION_FAILED. Async & state: Synchronous read; no state change. Datasets reflect the latest completed ingestion window; 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
groupBy?string

Dimension to group spend by (Cost Explorer "Group by" control).

Value in"service""project""region""tag"
tagKey?string

Tag key to group spend by when groupBy=tag (the Cost Explorer tag-key selector; ignored for the other dimensions). Resources whose usage carries that key group under <key>=<value>; resources without it fall under untagged. When omitted with groupBy=tag, the first key of the report's tagKeys is used (every row is untagged when there are none). 1..128 characters, else 422 VALIDATION_FAILED.

Length1 <= length <= 128
period?string

Reporting period (Cost Explorer period control). Ignored when an explicit from/to range is supplied.

Value in"7d""30d""90d""mtd"
from?string

Inclusive start of an arbitrary reporting window (UTC, ISO 8601). When supplied together with to, this explicit range REPLACES period. Both from and to must be provided together and from must be strictly before to, else 422 VALIDATION_FAILED.

Formatdate-time
to?string

Exclusive end of an arbitrary reporting window (UTC, ISO 8601). See from.

Formatdate-time
granularity?string

Bucket granularity (Cost Explorer granularity control).

Value in"daily""monthly"

Response Body

Paginated collection of cost report datasets for the requested dimensions.

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/cost-reports"
{  "data": [    {      "id": "string",      "groupBy": "service",      "period": "7d",      "granularity": "daily",      "rangeStart": "2019-08-24T14:15:22Z",      "rangeEnd": "2019-08-24T14:15:22Z",      "currency": "USD",      "dimensions": [        {          "id": "string",          "name": "string",          "color": "string"        }      ],      "series": [        {          "label": "string",          "date": "2019-08-24T14:15:22Z",          "property1": 0,          "property2": 0        }      ],      "total": 0,      "prevTotal": 0,      "breakdown": [        {          "id": "string",          "name": "string",          "color": "string",          "current": 0,          "previous": 0,          "spark": [            0          ],          "children": [            {              "id": "string",              "name": "string",              "resourceId": "string",              "resourceType": "string",              "current": 0,              "previous": 0,              "spark": [                0              ]            }          ]        }      ],      "tagKey": "string",      "tagKeys": [        "string"      ],      "coverage": "subscription"    }  ],  "meta": {    "page": 1,    "pageSize": 1,    "total": 0,    "hasNext": true  }}