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
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.
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 <= 20050cycle?stringRestrict to one billing cycle (the Hourly/Monthly counter filters).
"HOURLY""MONTHLY""ANNUAL"Page of billable resource subscriptions in the active scope.
application/json- response
data*array<>meta*Pagination envelope metadata. List responses are always { data, meta } — never a naked array.
coverage?BillingCoverageWhat 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.
"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"}