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
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.
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 <= 20050groupBy?stringDimension to group spend by (Cost Explorer "Group by" control).
"service""project""region""tag"tagKey?stringTag 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.
1 <= length <= 128period?stringReporting period (Cost Explorer period control). Ignored when an explicit from/to
range is supplied.
"7d""30d""90d""mtd"from?stringInclusive 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.
date-timeto?stringExclusive end of an arbitrary reporting window (UTC, ISO 8601). See from.
date-timegranularity?stringBucket granularity (Cost Explorer granularity control).
"daily""monthly"Paginated collection of cost report datasets for the requested dimensions.
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/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 }}