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 and query the transaction ledger

GET
/scopes/{scopeId}/billing/transactions

Returns the billing transaction ledger for the active tenant/subscription/project scope: charges, payments, applied credits, refunds and pending wire transfers, newest first. This single endpoint backs both the plain Transactions page load (billing.transaction.list) and every search/filter/sort/pagination interaction (billing.transaction.search_filter_sort): q matches the description, the ledger reference and the linked invoice number; type and status mirror the UI counter filters (All / Payments / Charges / Pending approval); sort accepts createdAt and amount. Amounts are signed integers in ten-thousandths of the currency unit — charges positive (increase the outstanding balance), payments/credits/refunds negative. No resource state is mutated. Validation: scopeId must reference a scope visible to the caller (unknown → NOT_FOUND); type, status, sort, order, page, pageSize must be within their declared enums/ranges, otherwise VALIDATION_FAILED (422); the caller needs reader-or-higher (or billing) role in the scope, otherwise FORBIDDEN. Async & state: Synchronous read; no state change. New ledger rows posted while the view is open arrive as resource.updated SSE frames with kind billing.transaction. Errors: 401 missing/expired session; 403 caller lacks billing read permission in the scope; 404 unknown scope; 422 malformed filter/pagination parameters; 429 burst polling rate-limited; 500 ledger read-model unavailable. Idempotency/Concurrency: Safe, cacheable; no idempotency key required. Stable sort keys plus page/pageSize make repeated reads deterministic for an unchanged ledger.

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
type?string

Filter by ledger entry type (UI counters group payment, wire-transfer-pending and refund as "Payments").

Value in"charge""payment""credit-applied""refund""wire-transfer-pending"
status?string

Filter by settlement status (the "Pending approval" counter maps to pending-manual-approval).

Value in"completed""pending""pending-manual-approval""failed"
invoiceId?string

Restrict the ledger to entries linked to a specific invoice.

Response Body

Page of transaction ledger entries in the active 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/transactions"
{  "data": [    {      "id": "string",      "type": "charge",      "description": "string",      "amount": 0,      "method": "string",      "status": "completed",      "invoiceId": "string",      "invoiceNumber": "string",      "reference": "string",      "createdAt": "2019-08-24T14:15:22Z",      "failureReason": "string",      "commitmentId": "string"    }  ],  "meta": {    "page": 1,    "pageSize": 1,    "total": 0,    "hasNext": true  }}