Usage and limits | Finbar Docs

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 and webhooks 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:

{
  "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 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

GET /v1/usage

Use an access token with https://api.finbar.com/read permission:

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 or MCP tool errors.