Read the workspace AI usage snapshot
Returns the current AI usage snapshot for the workspace and the calling user, including the balance and whether top-up packs are available. Any workspace member with a Clerk session may call it; API keys are rejected.
Authorization
apiKey Workspace API key created in Workspace settings → API keys. Scopes on the key bound what it can read and write.
In: header
Path Parameters
Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/v1/workspaces/string/billing/ai-usage"{ "data": { "plan": "free", "unlimited": true, "monthly": { "capMicrousd": 0, "usedMicrousd": 0, "remaining": 0, "refillsAt": "string" }, "burst": { "capMicrousd": 0, "usedMicrousd": 0, "remaining": 0, "refillsAt": "string" }, "onboardingGrantActive": true, "topupBalanceMicrousd": 0, "topupsAvailable": true }}{ "_tag": "ApiNotFound", "error": "not_found", "message": "That item does not exist, or this key cannot see it.", "status": 404}{ "_tag": "ApiNotFound", "error": "not_found", "message": "That item does not exist, or this key cannot see it.", "status": 404}Read the plan catalog with the workspace's current plan
Returns the purchasable plan catalog plus the workspace's effective plan and subscription status. Any workspace member with a Clerk session and a synced profile may call it, so members see only the effective plan rather than the full subscription record. If a pricing experiment is running the caller's deterministic variant selects the catalog and the exposure is recorded.
Read the detailed billing record for a workspace
Returns the expanded billing detail behind the subscription summary. Requires a Clerk session and the `billing:read` workspace permission.