Guides

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

HTTP
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 of reservedCents for calls that reached the provider but never reported back. It is already included in reservedCents; don't add it twice.
  • A row with actualCostCents: null has no final cost yet. null never 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.

LimitDefault
Requests600 a minute, across all keys
Runs in progress32 at once (paused runs don't count)
Open event streams32 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:

AnswerWhat to do
429 partner_request_capacityWait for Retry-After, then retry.
429 partner_run_capacityWait for Retry-After, then retry with the same Idempotency-Key.
429 stream_capacityClose streams you don't need, or wait for Retry-After.
429 budget_exhaustedThe 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 limitA 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.

Fin documentation Built from the API contract · v1

Search all documentation