Usage and limits
All your API keys share one account: one usage record and one set of limits. Adding keys or users doesn't add capacity. These limits cover requests and AI usage; they have nothing to do with the money in users' wallets.
Read your usage
GET /v1/partner/usage?periodKind=day&periodStart=2026-09-22&limit=100
X-Api-Key: fin_…This needs only your API key. For a month, send periodKind=month and the month's first day. The answer has totals, a page of rows in data, nextCursor and asOf. Keep passing nextCursor back as cursor to export every row. A period that is still open keeps changing, so treat an export as a report, not an invoice.
totals includes model calls for your users' runs, your partner's own runs, suggestions and voice transcriptions. suggestionTotals gives the suggestion portion of those same totals, voiceTotals the transcription portion, and partnerRunTotals the portion of runs Fin makes for your partner itself, such as market briefs; older servers omit these fields. The paginated data contains your users' run calls only, because a suggestion set and a transcription have no run and a partner run has no user. To reconcile a complete export with total inference usage, include the suggestion, voice and partner-run totals once each, not once per page. Costs are whole cents, so each transcription counts as one cent however short it is: ten thousand of them come to $100.
Each row is one run's AI model call: which user, agent and run made it, and what it cost. Costs are strings of whole US cents:
knownCostCents: calls whose cost is final.reservedCents: the maximum still held for calls whose final cost isn't known yet.uncertainReservedCents: the part ofreservedCentsfor calls that reached the provider but never reported back. It is already included inreservedCents; don't add it twice.- A row with
actualCostCents: nullhas no final cost yet.nullnever means zero.
Rows never contain prompts, messages or amounts of money. A call is always charged to the day and month it was made in, even if its cost is settled later.
Your limits
Get your rate limits returns your limits, what is in use now, and the spend caps for the current day and month. Its usage includes runs, suggestions and voice transcriptions. Use periods[].capCents for the effective allowance of an open UTC day or month, including any audited operator adjustment. limits.dayCapCents and limits.monthCapCents configure future periods and can differ from the caps of periods already open.
| Limit | Default |
|---|---|
| Requests | 600 a minute, across all keys |
| Runs in progress | 32 at once (paused runs don't count) |
| Open event streams | 32 at once, 4 per user |
| AI spend | $100 a day, $1,000 a month |
Each user also has their own AI usage budget; see Get AI usage budget. Each time fin reads a user's account again for suggestions, it spends from it like a chat message. Those reads count toward the user's 30 an hour and 200 a day, and an account is read at most once a minute; reading suggestions Fin already made costs nothing and counts toward neither. When the budget or those limits stop a read of the account, List suggestions keeps serving what still holds, and with nothing left it answers failed with retryable: false rather than an error.
When a limit is reached:
| Answer | What to do |
|---|---|
429 partner_request_capacity | Wait for Retry-After, then retry. |
429 partner_run_capacity | Wait for Retry-After, then retry with the same Idempotency-Key. |
429 stream_capacity | Close streams you don't need, or wait for Retry-After. |
429 budget_exhausted | The user's AI budget is used up (or frozen by an operator) until the next day or month. |
A failed run whose failure.code names a budget or spend limit | A limit had no room for the run's next model request. Tell the user which one, not that the model failed, and read the run's trades before they ask again. The codes are in Budgets and limits. |
A stream holds its slot while it is open. If your process dies without closing it, the slot frees itself within about a minute.
Changing limits
Your API key can read limits but not change them; ask your deployment operator. New request, run and stream limits apply straight away to new work; running work finishes. A new daily or monthly spend cap applies from the next day or month unless the operator explicitly applies it to the current UTC periods too. That audited adjustment takes effect immediately for new model reservations and preserves all recorded spend and outstanding reservations.