# 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](/api-reference/partner/quotas) 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](/api-reference/budgets/get). Each time fin reads a user's account again for
[suggestions](/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](/concepts#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.
