Billing & Usage Export

BuilderStudio meters usage in credits. You can read a workspace's balance and transactions programmatically, and export usage as a FOCUS v1.3 cost-and-usage dataset for ingestion into a FinOps tool. All billing reads require the read:billing scope on a workspace builder_ key.

Credit balance and transactions

These read endpoints return live credit data for the key's workspace.

1curl https://<deployment>.convex.site/api/mcp/credits/balance \2  -H "Authorization: Bearer builder_..."3 4# -> { "workspaceId": "...", "balance": <credits>, ... }

FOCUS usage export

Two endpoints back the export. They are reachable on the BuilderStudio app origin at /api/billing/*; when you send a workspace builder_ key the app proxies the request to Convex, which derives the workspace from the key. (The same URLs also serve signed-in dashboard sessions, which must instead pass an explicit workspaceId query parameter.)

Query parameters

• from, to — the date range. The window may span at most 365 days.
• format — jsonl (default) or csv. Applies to focus-export only.
• For dashboard-session requests, also pass workspaceId. API-key requests omit it — the workspace comes from the key.

Response

The export is returned as a file attachment: application/jsonl (focus-export.jsonl) or text/csv (focus-export.csv). Responses are sent with Cache-Control: no-store.

1# JSONL (default)2curl -L "https://<your-app-host>/api/billing/focus-export?from=1714521600000&to=1717200000000" \3  -H "Authorization: Bearer builder_..." \4  -o focus-export.jsonl5 6# CSV7curl -L "https://<your-app-host>/api/billing/focus-export?from=...&to=...&format=csv" \8  -H "Authorization: Bearer builder_..." \9  -o focus-export.csv10 11# Dataset metadata12curl "https://<your-app-host>/api/billing/focus-metadata?from=...&to=..." \13  -H "Authorization: Bearer builder_..."