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 billable resource subscriptions with search, filter, sort and pagination

GET
/scopes/{scopeId}/billing/subscriptions

Returns the per-resource recurring subscriptions (billable resources) in the active tenant/subscription/project scope, as rendered by the Subscriptions view: one row per billable resource with its billing cycle, unit price and usage-to-date in ten-thousandths of the currency unit, quantity and next invoice date. This single operation serves both the plain route-load list and the search/filter/sort/paginate variant (billing.billing_subscription.search_filter_sort): q matches free text over name and service; cycle narrows to the Hourly/Monthly counter filters; sort accepts service | name | unitPrice | usageToDate with order asc|desc. KPI rollups (monthly run rate, usage this period) are computed client-side from this data. Validation: caller must hold at least the reader or billing role in the scope (else 403); scopeId must resolve to a visible tenant/subscription/project (else 404 NOT_FOUND); page >= 1, pageSize 1..200, cycle/order must be enum members and sort a supported field — violations map to 422 VALIDATION_FAILED naming the offending field. Async & state: Synchronous read; no state change. No operation is created and no resource.updated SSE frames are emitted. Errors: 401 missing/expired session; 403 role lacks billing read access in this scope; 404 unknown scopeId; 422 malformed pagination, sort or enum filter values; 500 internal. Idempotency/Concurrency: Safe, cacheable; no idempotency key required. The response is always the { data, meta } envelope — never a naked array.

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

Restrict to one billing cycle (the Hourly/Monthly counter filters).

Value in"HOURLY""MONTHLY""ANNUAL"

Response Body

Page of billable resource subscriptions in the active scope.

application/json
  1. response
data*array<>
meta*

Pagination envelope metadata. List responses are always { data, meta } — never a naked array.

coverage?BillingCoverage

What the figures of a cost view cover. subscription: every project of the subscription -- the caller holds a subscription-level billing grant. project: only the path project -- the caller's grant covers that project alone; subscription-level money (credits, invoices) is not part of the view. Absent is subscription.

Value in"subscription""project"
curl -X GET "https://example.com/scopes/string/billing/subscriptions"
{  "data": [    {      "id": "string",      "service": "string",      "name": "string",      "cycle": "HOURLY",      "unitPrice": 0,      "qty": 0,      "usageToDate": 0,      "nextInvoiceAt": "string",      "status": "active",      "unpriced": false    }  ],  "meta": {    "page": 1,    "pageSize": 1,    "total": 0,    "hasNext": true  },  "coverage": "subscription"}