> For the complete documentation index, see [llms.txt](https://mute-sh.gitbook.io/mute.sh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mute-sh.gitbook.io/mute.sh/api/getting-started/rate-limits.md).

# Rate Limits & Quotas

Two independent meters apply to every request:

1. **Per-minute rate limit** — a sliding bucket sized by your tier (10/min free → 50,000/min Enterprise).
2. **Monthly token quota** — 1 token per request, reset each calendar month (`X-Quota-Period` tells you which month is being metered).

Anonymous requests are metered **by IP**; keyed requests are metered **per organization**, so all keys in your org share one bucket and one quota.

## The headers on every response

Real headers from a live Enterprise-tier response:

```
ratelimit-limit: 50000          ← per-minute bucket size (IETF draft form)
ratelimit-remaining: 49999
ratelimit-reset: 1783081564     ← unix seconds when the bucket refills
x-ratelimit-limit: 50000        ← same trio, X- prefixed for older clients
x-ratelimit-remaining: 49999
x-ratelimit-reset: 1783081564
x-quota-limit: unlimited        ← monthly quota (number, or "unlimited")
x-quota-used: 10
x-quota-remaining: unlimited
x-quota-period: 2026-07         ← the calendar month being metered
x-tier: enterprise              ← the tier your request resolved to
```

`x-tier` is the fastest way to confirm your key is being picked up: `free` means you're anonymous (or on a free key); anything else means the key resolved.

## When you go over

* **Over the per-minute bucket** → `429` with a `Retry-After` header (seconds). Back off and retry after that.
* **Over the monthly quota** → `429` on the free tier (hard stop until the month rolls over). Paid tiers flow into metered overage instead of stopping — see [Pricing](/mute.sh/api/getting-started/pricing.md#overage). Enterprise has fair-use soft limits.

A well-behaved client:

```ts
const res = await fetch(url, { headers: { "X-API-Key": key } });
if (res.status === 429) {
  const wait = Number(res.headers.get("retry-after") ?? "5");
  await new Promise((r) => setTimeout(r, wait * 1000));
  return retry();
}
// pace long batch jobs off the live meters
const remaining = res.headers.get("x-quota-remaining");
```

## Getting more out of your quota

* **Respect `Cache-Control`.** Many reads are server-cacheable and tell you for how long: hot stats endpoints send `no-store`, slower-moving reads send 30 s or 1 h max-age, and settled/immutable data is marked `immutable`. Caching on your side directly saves tokens.
* **Prefer bulk endpoints** over per-item loops — e.g. one call to `/v1/markets/coin-labels` or `/v1/markets/logos` replaces hundreds of per-coin lookups.
* **Use SSE for live data** instead of polling: one long-lived `/v1/activity/stream` connection replaces a poll loop. Stream connections have their own caps (500 global, 3 concurrent per key/IP, 30 min per connection — reconnect to continue).
* **Filter server-side** (`underlying`, `market_class`, `min_notional`, `limit`) rather than downloading broad result sets and filtering locally.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://mute-sh.gitbook.io/mute.sh/api/getting-started/rate-limits.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.