> For the complete documentation index, see [llms.txt](https://mcp-docs.nichefire.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mcp-docs.nichefire.com/errors-and-limits/quota.md).

# Quota

Your quota is the total amount of **live research** your organization can run. It is what you are actually buying: each search or trend analysis draws one unit from a shared pool.

It is not the same thing as a rate limit. A rate limit slows you down for a given certain amount of time; an exhausted quota stops research until the allowance is topped up.

### What consumes quota

Only the Firesearch research tools — the ones that go out to the public web.

| Tool                | Cost                | Why                                                  |
| ------------------- | ------------------- | ---------------------------------------------------- |
| `execute_search`    | **1 unit** per call | Runs live research across news, social, and the web. |
| `analyze_trend`     | **1 unit** per call | Runs a deep research pass on a single trend.         |
| `list_trend_topics` | Free                | Reads your organization's saved data.                |
| `get_trend_topic`   | Free                | Reads your organization's saved data.                |
| `list_trends`       | Free                | Reads your organization's saved data.                |
| `get_trend`         | Free                | Reads your organization's saved data.                |
| `get_usage`         | Free                | Reports your balance.                                |

Both research tools draw from the **same pool**. There is no separate allowance for analysis — ten searches and ten analyses cost the same twenty units.

Everything else is unmetered by quota, though still subject to a rate limit. Exploring what your organization already tracks never costs you anything.

### The pool is shared

Quota belongs to the **organization**, not to a person, a client, or a connector. Every search anyone runs — from Claude, from ChatGPT, from a script, through OAuth or an API key — draws from the same balance.

Two practical consequences:

* Exhausting the quota blocks your teammates, not just you.
* The numbers you see in [`get_usage`](/tools/get-usage.md) reflect everyone's activity, so they can move between two of your own calls.

### Checking your balance

Ask your assistant to check usage, or call `get_usage`. Features that meter a quota report a `quota` block:

```json
{
  "usage": {
    "firesearch": {
      "rate_limit": { "limit": 60, "remaining": 58, "reset_at": "2026-07-23T14:05:00Z", "window_seconds": 60 },
      "quota": { "limit": 1000, "used": 42, "remaining": 958 }
    },
    "insights": {
      "rate_limit": { "limit": 50, "remaining": 47, "reset_at": "2026-07-23T14:05:00Z", "window_seconds": 60 }
    }
  }
}
```

| Field       | Meaning                                       |
| ----------- | --------------------------------------------- |
| `limit`     | Total units in your organization's allowance. |
| `used`      | Units consumed so far.                        |
| `remaining` | Units left.                                   |

Trend Insights has no `quota` block at all — that is not an omission, it is the point: reading your own saved data is not metered.

### When it runs out

The call fails with **HTTP 429** and this body:

```json
{ "error": "Rate limit exceeded", "reason": "quota_exceeded" }
```

The message reads *Rate limit exceeded*, but the `reason` is `quota_exceeded` — and the difference matters. A rate limit clears itself within a minute; **an exhausted quota does not**. Waiting will not help. Contact your Nichefire representative for a top-up.

See [Errors](/errors-and-limits/errors.md) for how to tell the two apart at a glance.

### Working within it

* **Check before fanning out.** Call [`get_usage`](/tools/get-usage.md) before issuing several searches in a row.
* **If you are an agent acting for someone, ask first.** Running four angles on a topic costs four units of a pool the whole organization shares. Offer the trade-off rather than deciding it — for example: *"You have 958 searches left. I can run four angles for better coverage, or one to conserve quota."*
* **Search once, then analyze.** Re-running a near-identical prompt rarely adds much; passing a result to [`analyze_trend`](/tools/firesearch/analyze-trends.md) usually adds more for the same one unit.
* **Reading saved data is free.** When the answer might already be in your organization's Trend Insights, look there first — it costs nothing.