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 credit consumption events in the active scope

GET
/scopes/{scopeId}/billing/credits/events

Returns the credit application (consumption) events for the active tenant/subscription scope, newest first, as rendered by the Consumption history table of the Credits page. Each event records which credit grant was drawn down, what it was applied against (an invoice settlement or a service usage bucket), the amount consumed (in ten-thousandths of the currency unit) and the grant's remaining balance after the application. The same endpoint feeds the "Applied this month" metric tile, which sums amount over events whose at falls in the current calendar month — clients use the month filter for that roll-up. creditId narrows the history to a single grant; q, sort, order, page and pageSize apply standard collection semantics. Validation: scopeId must reference a scope the caller can access (otherwise 403 FORBIDDEN); month, when supplied, must match YYYY-MM (otherwise 422 VALIDATION_FAILED); unknown sort keys map to 422 VALIDATION_FAILED. Async & state: Synchronous read; no state change. No SSE frames are emitted. Errors: 401 when unauthenticated; 403 when the caller lacks billing read access in the scope; 422 for malformed query parameters (bad month format, unknown sort key, invalid pagination); 500 on backend 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
creditId?string

Restrict the history to events drawn from a single credit grant.

month?string

Restrict events to a calendar month (YYYY-MM, matched against the event's at timestamp); used by the Applied-this-month metric roll-up.

Match^[0-9]{4}-[0-9]{2}$

Response Body

Paginated collection of credit consumption events, newest first.

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/credits/events"
{  "data": [    {      "id": "ce-0607",      "at": "2019-08-24T14:15:22Z",      "creditId": "cr-migration",      "creditLabel": "Migration accelerator",      "appliedTo": "Compute — G-series usage",      "invoiceId": "inv-2026-06",      "amount": 0,      "remainingAfter": 0    }  ],  "meta": {    "page": 1,    "pageSize": 1,    "total": 0,    "hasNext": true  }}