Metering API
Usage metering and chargeback: usage reads, chargeback reports, and chargeback rate management.
4 routes
Response metadata: x-api-version, x-request-id, and traceresponse apply to normal routed responses and are omitted from the per-operation header tables below.
GET/api/metering/chargeback
audit access
Allocate cost per site by applying the per-request-type rates to the usage in the window.
AUDIT-tier (cross-site cost data). The window defaults to the last 90 days. NOTE: the totals assume a SINGLE currency across the active rates; a request type with no rate contributes 0 cost. 503 when no DB.
Permissions
| Access class | Credential | Scoping |
|---|---|---|
audit | An authenticated session or API bearer token is required. | The access class is enforced first; site and environment scopes narrow resources on scoped operations. |
HTTP request
GET https://<your-host>/api/metering/chargebackPath parameters
This operation has no path parameters.
Query parameters
| Name | Type | Requirement | Description |
|---|---|---|---|
since | string | Optional | Value supplied for the since query parameter. |
until | string | Optional | Value supplied for the until query parameter. |
site | string | Optional | Site identifier used to scope or filter the operation. |
Request headers
| Name | Type | Requirement | Description |
|---|---|---|---|
Authorization | string | Optional | Human credential alternative: supply one Bearer rys_... session token, ryk_... API token, or validated identity-provider JWT here. Do not combine it with X-Ryuki-Session-Id or the session cookie; conflicting carriers fail closed. |
X-Ryuki-Session-Id | string | Optional | Opaque rys_... session-token carrier used by the portal for mutations. Administrative session UUIDs cannot authenticate. Supply exactly one credential carrier per request. |
traceparent | string | Optional | Optional correlation input. When the second dash-separated segment has 32 characters, Ryuki reuses it as the request correlation identifier; this is not full W3C validation. |
Request body
This operation does not accept a request body.
Response
| Status | Description | Body |
|---|---|---|
200 | OK | Value |
200 response body
Structure: Value.
| Name | Type | Requirement | Description |
|---|---|---|---|
sites | JSON value | Required | Value of sites returned in the response body. |
total_cost | JSON value | Required | Value of total_cost returned in the response body. |
currency | JSON value | Required | Value of currency returned in the response body. |
unrated_request_types | JSON value | Required | Value of unrated_request_types returned in the response body. |
complete | JSON value | Required | Value of complete returned in the response body. |
basis | string | Required | Value of basis returned in the response body. |
window_since | JSON value | Required | Value of window_since returned in the response body. |
window_until | JSON value | Required | Value of window_until returned in the response body. |
Errors
JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.
Examples
Request
curl --silent --show-error --globoff \
--request GET \
--header 'Authorization: Bearer <token>' \
'https://<your-host>/api/metering/chargeback'Schematic response body
Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.
Success status: 200
{
"sites": null,
"total_cost": null,
"currency": null,
"unrated_request_types": null,
"complete": null,
"basis": "<string>",
"window_since": null,
"window_until": null
}GET/api/metering/chargeback/rates
audit access
List the configured cost rates.
Audit-tier.
Permissions
| Access class | Credential | Scoping |
|---|---|---|
audit | An authenticated session or API bearer token is required. | The access class is enforced first; site and environment scopes narrow resources on scoped operations. |
HTTP request
GET https://<your-host>/api/metering/chargeback/ratesPath parameters
This operation has no path parameters.
Query parameters
| Name | Type | Requirement | Description |
|---|---|---|---|
limit | integer | Optional | Maximum number of results requested. |
offset | integer | Optional | Number of results to skip before returning the page. |
Request headers
| Name | Type | Requirement | Description |
|---|---|---|---|
Authorization | string | Optional | Human credential alternative: supply one Bearer rys_... session token, ryk_... API token, or validated identity-provider JWT here. Do not combine it with X-Ryuki-Session-Id or the session cookie; conflicting carriers fail closed. |
X-Ryuki-Session-Id | string | Optional | Opaque rys_... session-token carrier used by the portal for mutations. Administrative session UUIDs cannot authenticate. Supply exactly one credential carrier per request. |
traceparent | string | Optional | Optional correlation input. When the second dash-separated segment has 32 characters, Ryuki reuses it as the request correlation identifier; this is not full W3C validation. |
Request body
This operation does not accept a request body.
Response
| Status | Description | Body |
|---|---|---|
200 | OK | Value |
200 response body
Structure: Value.
| Name | Type | Requirement | Description |
|---|---|---|---|
rates | JSON value | Required | Value of rates returned in the response body. |
durable | boolean | Required | Value of durable returned in the response body. |
total | JSON value | Required | Total number of matching items before the returned page is applied. |
limit | JSON value | Required | Page-size limit applied to this response. |
offset | JSON value | Required | Number of matching items skipped before this response page. |
Returns a paginated JSON object with total/limit/offset keys.
Errors
JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.
Examples
Request
curl --silent --show-error --globoff \
--request GET \
--header 'Authorization: Bearer <token>' \
'https://<your-host>/api/metering/chargeback/rates'Schematic response body
Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.
Success status: 200
{
"rates": null,
"durable": false,
"total": null,
"limit": null,
"offset": null
}POST/api/metering/chargeback/rates
admin access
Set (upsert) a request-type unit cost.
ADMIN-tier: billing rates must not be rewritable by any operator who can run workload. 503 when no DB.
Permissions
| Access class | Credential | Scoping |
|---|---|---|
admin | An authenticated session or API bearer token is required. | The access class is enforced first; site and environment scopes narrow resources on scoped operations. |
HTTP request
POST https://<your-host>/api/metering/chargeback/ratesPath parameters
This operation has no path parameters.
Query parameters
This operation has no query parameters.
Request headers
| Name | Type | Requirement | Description |
|---|---|---|---|
Authorization | string | Optional | Human credential alternative: supply one Bearer rys_... session token, ryk_... API token, or validated identity-provider JWT here. Do not combine it with X-Ryuki-Session-Id or the session cookie; conflicting carriers fail closed. |
Content-Type | string | Required | Required by the resolved Axum Json<T> request extractor; send application/json. |
X-Ryuki-Session-Id | string | Optional | Opaque rys_... session-token carrier used by the portal for mutations. Administrative session UUIDs cannot authenticate. Supply exactly one credential carrier per request. |
Idempotency-Key | string | Optional | Optional at-most-once retry key for human mutations. When omitted, the idempotency middleware passes the request through without deduplication. |
traceparent | string | Optional | Optional correlation input. When the second dash-separated segment has 32 characters, Ryuki reuses it as the request correlation identifier; this is not full W3C validation. |
Request body
JSON structure: CostRateRequest.
| Name | Type | Requirement | Description |
|---|---|---|---|
request_type | string | Required | Value of request_type in the JSON request body. |
unit_cost | number | Required | Value of unit_cost in the JSON request body. |
currency | string | Optional | Value of currency in the JSON request body. |
Response
| Status | Description | Body |
|---|---|---|
200 | OK | Value |
200 response body
Structure: Value.
| Name | Type | Requirement | Description |
|---|---|---|---|
request_type | JSON value | Required | Value of request_type returned in the response body. |
unit_cost | JSON value | Required | Value of unit_cost returned in the response body. |
currency | JSON value | Required | Value of currency returned in the response body. |
set | boolean | Required | Value of set returned in the response body. |
Errors
JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.
Examples
Request
curl --silent --show-error --globoff \
--request POST \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '{"request_type":"<string>","unit_cost":0.0}' \
'https://<your-host>/api/metering/chargeback/rates'Schematic response body
Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.
Success status: 200
{
"request_type": null,
"unit_cost": null,
"currency": null,
"set": false
}GET/api/metering/usage
audit access
Per-site usage, metered as the count of requests raised in the window, broken down by status.
AUDIT-tier: this exposes cross-site operational/chargeback volume, so it sits with the read-only reporting role, not every operator. Both window endpoints are constrained to the last 90 days of server time, so neither an old lower bound nor an old historical slice can turn this into an attacker-selected history scan. 503 when no database is configured.
Permissions
| Access class | Credential | Scoping |
|---|---|---|
audit | An authenticated session or API bearer token is required. | The access class is enforced first; site and environment scopes narrow resources on scoped operations. |
HTTP request
GET https://<your-host>/api/metering/usagePath parameters
This operation has no path parameters.
Query parameters
| Name | Type | Requirement | Description |
|---|---|---|---|
since | string | Optional | Value supplied for the since query parameter. |
until | string | Optional | Value supplied for the until query parameter. |
site | string | Optional | Site identifier used to scope or filter the operation. |
Request headers
| Name | Type | Requirement | Description |
|---|---|---|---|
Authorization | string | Optional | Human credential alternative: supply one Bearer rys_... session token, ryk_... API token, or validated identity-provider JWT here. Do not combine it with X-Ryuki-Session-Id or the session cookie; conflicting carriers fail closed. |
X-Ryuki-Session-Id | string | Optional | Opaque rys_... session-token carrier used by the portal for mutations. Administrative session UUIDs cannot authenticate. Supply exactly one credential carrier per request. |
traceparent | string | Optional | Optional correlation input. When the second dash-separated segment has 32 characters, Ryuki reuses it as the request correlation identifier; this is not full W3C validation. |
Request body
This operation does not accept a request body.
Response
| Status | Description | Body |
|---|---|---|
200 | OK | Value |
200 response body
Structure: Value.
| Name | Type | Requirement | Description |
|---|---|---|---|
sites | JSON value | Required | Value of sites returned in the response body. |
site_count | JSON value | Required | Value of site_count returned in the response body. |
total_requests | JSON value | Required | Value of total_requests returned in the response body. |
window_since | JSON value | Required | Value of window_since returned in the response body. |
window_until | JSON value | Required | Value of window_until returned in the response body. |
Errors
JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.
Examples
Request
curl --silent --show-error --globoff \
--request GET \
--header 'Authorization: Bearer <token>' \
'https://<your-host>/api/metering/usage'Schematic response body
Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.
Success status: 200
{
"sites": null,
"site_count": null,
"total_requests": null,
"window_since": null,
"window_until": null
}