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 and query credit grants in the active scope
Returns the credit grants (coupons, promotions, support credits and prepaid top-ups) visible in the
active tenant/subscription/project scope, as rendered by the Credits page on route load. Each grant
carries its granted/consumed/remaining balances in ten-thousandths of the currency unit, its lifecycle status (active, exhausted,
expired) and its ARN-style reference. This single endpoint also serves the search/filter/sort/paginate
behavior (billing.credit.search_filter_sort): the UI exposes status chips (All / Active / Exhausted /
Expired) which map to the status query parameter, and source narrows by grant origin; q, sort,
order, page and pageSize apply standard collection semantics. Plain list = same call with no
filter parameters.
Validation: scopeId must reference a scope the caller can access (otherwise 403 FORBIDDEN);
status must be one of active|exhausted|expired and source one of coupon|promo|support-credit|prepaid
(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 read access to the billing scope
(reader and billing roles and above may read); 422 for malformed query parameters; 500 on backend
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 <= 20050status?stringFilter credit grants by lifecycle status (UI status chips).
"active""exhausted""expired"source?stringFilter credit grants by origin.
"coupon""promo""support-credit""prepaid"Paginated collection of credit grants in the active scope.
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/credits"{ "data": [ { "id": "cr-prepaid-apr", "source": "coupon", "label": "Prepaid top-up — wire transfer", "code": "WELCOME2026", "granted": 0, "consumed": 0, "remaining": 0, "grantedAt": "2019-08-24T14:15:22Z", "expiresAt": "2019-08-24T14:15:22Z", "status": "active", "reference": "arn:publiccloud:billing:ist-1:acct-1:credit/cr-prepaid-apr" } ], "meta": { "page": 1, "pageSize": 1, "total": 0, "hasNext": true }}