> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retailgrid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage & limits

> How Retailgrid meters API and MCP usage per organization, what happens when the budget is exhausted, and how to back off.

Retailgrid meters usage so one pipeline — or one runaway loop — can't exhaust the resources behind everyone else's. Reads, writes, exports, and polling all count, across the [public API](/api-reference/introduction) and the [MCP connector](/settings/ai-connections) alike.

## What's metered, and at what grain

Usage is accounted **per organization**. The budget is shared across every API key, every user, and the MCP connector, so spreading calls over more keys or more endpoints does not raise your ceiling — it all draws on the same organization budget.

Usage is tracked along a few **dimensions**, each with its own `unit`:

| Unit | What it counts |
| :- | :- |
| `requests` | Individual API requests. |
| `calls` | MCP tool calls. |
| `active_work` | Concurrent in-flight work (long operations and jobs). |
| `bytes` | Data volume moved by an operation, e.g. a large export. |

## When the budget is exhausted

An exhausted budget is rejected **before** any expensive processing, so you are not billed for work that never ran. The response is `429 Too Many Requests` with:

* a `Retry-After` header, and
* a JSON body whose `detail` reports exactly what was hit and when it clears.

```json theme={null}
{
  "detail": {
    "code": "organization_usage_limit_exceeded",
    "dimension": "transactions_read",
    "unit": "requests",
    "limit": 100000,
    "remaining": 0,
    "request_id": "0b3c1f4a-9c1d-4f2a-8a3b-2c3d4e5f6a7b",
    "reset_at": "2026-10-08T00:00:00Z",
    "retry_after": 3600
  }
}
```

`reset_at` is when the budget refills; `retry_after` is the same wait in seconds and mirrors the `Retry-After` header. Because the budget is shared, switching to another API key does **not** restore access — wait for the reset.

## How to behave well

* **Honour `Retry-After`.** Back off for the stated interval rather than retrying immediately; a tight retry loop just burns the next window too.
* **Don't fan out across keys** to dodge the limit — it's one organization budget.
* **Prefer bulk and async endpoints** over many small calls (see [Imports vs bulk](/api-reference/imports-vs-bulk)); they move the same data for far fewer requests.
* **Poll on a sane cadence.** For async jobs, every 5–10s for active jobs and 30–60s for queued ones is plenty (see [Conventions ▸ Async jobs](/api-reference/conventions)).

## If enforcement is unavailable

If the usage-enforcement service itself is temporarily unavailable, the API returns `503` with `{ "detail": { "code": "usage_enforcement_unavailable" } }`. This is transient — retry after a short delay.

## Related

* [Conventions](/api-reference/conventions)
* [Errors](/api-reference/errors)
* [Imports vs bulk](/api-reference/imports-vs-bulk)
* [AI connections (MCP)](/settings/ai-connections)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.