# 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 and market-data 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.

## Watchlists and webhooks

Watchlist requests, webhook inbox reads, and webhook management each have a
separate account limit of 60 requests per minute, with a burst of 10.
They do not use the document-read allowance. Reading a document after receiving
an event uses the normal allowance.

See [watchlists](https://docs.finbar.com/api-mcp/watchlists.md) and [webhooks](https://docs.finbar.com/api-mcp/webhooks.md) for setup
and polling examples.

## Discover document read permissions

`GET /v1/account/permissions` and MCP `get_account_permissions` return your
effective document read allowances, including customer overrides. Both require
`read`. These endpoints report allowances; they do not change permissions.

An Enterprise account normally receives:

```json
{
  "document_read": {
    "max_chunks_per_request": 100,
    "max_chars_per_chunk": 10000
  }
}
```

Free and personal plans retain 10 chunks per request. All plans normally cap
each chunk at 10,000 Unicode characters, excluding the abbreviation notice.
For a previously truncated item whose full text is specifically needed, a
direct item read can set `disable_truncate` to true.

## Dataset build and update AI usage

[Build Dataset and Update Dataset](https://docs.finbar.com/api-mcp/build-update-datasets.md) consume account AI credits for
actual research usage, including work performed before failure or cancellation.
Status polling and result retrieval do not incur AI charges. Each dataset run
reports its own tokens, charges and billing status.

## 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/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.

Token requests to `https://auth.finbar.com/oauth2/token` are not included in
Finbar request usage, whether they succeed or fail. Authentication failures,
scope rejections, unknown routes and requests rejected by rate limits also do
not create API usage records. An admitted API operation that later returns a
server error does count, including a failed webhook listing. When reconciling
usage, compare the requested date range and the response's `as_of` timestamp.

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 `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).
