Balance and usage
Read your credits with the same key you use for requests.
These are OpenAI's legacy billing endpoints, so tools that already read them work unchanged. They cost nothing. Values are for the whole account.
Balance
curl https://api.caft.dev/v1/dashboard/billing/subscription \ -H "Authorization: Bearer $CAFT_API_KEY"
{
"object": "billing_subscription",
"has_payment_method": true,
"soft_limit_usd": 12.5,
"hard_limit_usd": 12.5,
"system_hard_limit_usd": 12.5,
"access_until": 0
}| Field | Meaning |
|---|---|
hard_limit_usd | Credits bought to date, in USD: what you have left plus what you have spent. |
soft_limit_usd | Same as hard_limit_usd. |
access_until | 0: keys don't expire. |
Usage
curl https://api.caft.dev/v1/dashboard/billing/usage \ -H "Authorization: Bearer $CAFT_API_KEY"
{
"object": "list",
"total_usage": 398.0
}total_usage is all-time spend in US cents. Your balance is hard_limit_usd - total_usage / 100, the same figure Billing shows as Available balance.
Per-request detail
The API has no per-day or per-model breakdown; the dashboard's Usage page does. Pick a date range and, optionally, one API key to see requests, tokens, spend and what the same tokens would have cost at the model vendor's list price, then usage by model and cache performance. Cache performance counts only second-and-later turns of a conversation, so first turns don't count as misses. The request log below lists each request with its time, model, key, HTTP status, input, output and cached tokens, the price it was billed at, time to first token (TTFT), output tokens per second and cost, and can be filtered by status, key and model. Failed requests show their status in red; hover it for the reason. A stream your client closed early shows 499.
To track spend in your own app, add "stream_options": {"include_usage": true} to streamed requests and multiply the token counts by the prices.
Plan usage
The endpoints above report your credit balance only. Requests paid by a monthly plan don't reduce it and don't appear in total_usage. To read a plan's limits, use the X-Caft-Plan-* response headers or GET https://caft.dev/api/plan; see Check your usage. On the dashboard's Usage page, each request is tagged Plan or Balance by what paid for it, and a plan request shows the plan credits it used instead of a price.