Metering API

Usage metering and billing

REST API endpoints for Metering. 5 operations.

Get usage summary

plaintext

GET /api/v1/usage

Returns the caller's aggregate usage summary.

Auth: Bearer API key

Responses

operationId: getUsageSummary

plaintext

GET /v1/usage/keys

Returns each of the organization's API keys with its request count for the current billing month. Requires the metering:read scope.

Auth: Bearer API key

Responses

Status	Description
`200`	Per-API-key request counts for the current month
`401`	Missing or invalid API key
`403`	Token lacks the metering:read scope
`500`	Internal error

operationId: getKeysUsage

plaintext

GET /v1/usage/keys/{key_id}

Returns the request count for a single API key this billing month. Requires the metering:read scope; the key must belong to the caller's org.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`key_id`	path	`string`	Yes	API key id (UUID)

Responses

Status	Description
`200`	Usage detail for one API key this month
`401`	Missing or invalid API key
`403`	Token lacks the metering:read scope
`404`	Key not found in this organization
`500`	Internal error
`501`	Billing not configured

operationId: getKeyUsage

plaintext

GET /v1/user/budget

Returns current usage (AI tokens, storage, compute hours), the plan's allowances, and the remaining headroom for each.

Auth: Bearer API key

Responses

Status	Description
`200`	Usage, plan limits, and remaining allowance
`401`	Missing or invalid credentials
`500`	Database error

operationId: getUserBudget

plaintext

GET /v1/user/stats

Returns a per-service usage breakdown (AI, storage, compute, bandwidth, functions) for the current month.

Auth: Bearer API key

Responses

Status	Description
`200`	Per-service usage for the current month
`401`	Missing or invalid credentials
`500`	Database error

operationId: getUserStats