# Usage and limits

Understand shared request allowances and read account usage through the API.

Source: <https://docs.finbar.com/api-mcp/usage>

REST API and MCP requests share your account's allowances. Connecting another
assistant or creating another credential does not add a separate allowance.
A single assistant prompt may make several tool calls, each of which is a
separate request.

## How limits work

Company, document, market-data and dataset reads share the data-request limits.
Your plan determines the allowed request rate and daily allowance. Daily
allowances reset at midnight UTC.

A request that passes the limit checks counts toward the allowance even if
its later validation or execution fails. A request rejected because the limit
has already been reached does not consume another request.

| Interface | When a limit is reached                                                    |
| --------- | -------------------------------------------------------------------------- |
| REST API  | HTTP `429`; wait for the number of seconds in the `Retry-After` header     |
| MCP       | Tool error with code `rate_limit_exceeded`; wait for `retry_after_seconds` |

The retry delay accounts for both short-term rate limits and daily limits.
Follow the returned delay instead of immediately repeating the request.

## Read usage through the REST API

```text
GET /v1/usage
```

Use an [access token](https://docs.finbar.com/api-mcp/authentication.md) with
`https://api.finbar.com/usage:read` permission:

```bash
curl --fail-with-body --silent --show-error --get \
  'https://api.finbar.com/v1/usage' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode 'start_date=2026-09-01' \
  --data-urlencode 'end_date=2026-09-07'
```

Both dates are included. A request can cover up to 92 days. The response contains
`totals` for the range and `daily` breakdowns, along with `as_of`, the time of
the usage read. Recent requests may take a short time to appear.

There is no equivalent MCP usage tool. Use the REST API when you need to
retrieve usage programmatically.

## What the limits endpoint reports

`GET /v1/limits` uses the same `usage:read` permission. It reports account AI
credits and research-run limits. It does **not** report the number of data
requests remaining today. Use the retry delay when a data-request limit is
reached.

For other failures, see [REST errors](https://docs.finbar.com/api-mcp/errors.md) or
[MCP tool errors](https://docs.finbar.com/api-mcp/mcp-tools.md#tool-errors).