Usage lifecycle
Reserve, finalize, void, and track for metered usage.
Usage follows a short lifecycle: the product reserves an estimated cost, finalizes the actual charge, or voids the reservation when generation fails. This page shows the chat flow and the corresponding Developer API reads.
Chat
If the reservation fails because the wallet has insufficient balance, an API
client receives 402 with insufficient_ftai.
Failed generation voids the reservation.
API equivalents
Reserve, finalize, void, and track are product-server operations used by the chat flow above. They are not part of the API-key Developer API.
| Phase | Operation | Effect |
|---|---|---|
| Reserve | Usage reserve | Hold grants; status reserved |
| Finalize | Usage finalize | Debit actual cost; release unused hold |
| Void | Usage void | Restore held grants |
| Track | Usage track | Single-step debit |
The Developer API exposes usage reads and a pre-flight balance check instead:
| Request | Effect |
|---|---|
POST /v1/billing/usage/check | Checks the required balance and can optionally record the charge. |
POST /v1/billing/usage/query | Returns grouped usage. |
GET /v1/billing/usage/summary | Returns usage totals for a date range. |
See API overview.
Cost resolution
Usage cost follows the selected model's published rate and the event's token counts. When an event supplies an explicit supported cost, that value is used. A small minimum charge may apply when no catalog rate matches.
See LLM usage.
Remaining usage in the app
The app sidebar shows one billing prompt at a time. While more than half of the included FTAI remains, it shows the referral invite. At 50% remaining or less, or when no referral is available, it shows the plan card with a remaining-usage meter and an upgrade action.
Next steps
- LLM usage - see how model tokens are metered
- Billing controls - choose what happens when FTAI runs out
- API overview - review authentication and billing endpoints