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

# Rate Limits

> Understand the request limits that apply to each MoltSets plan.

Rate limits vary by plan. All limits are per API key.

To prevent abuse, Unlimited Plans are subject to our [Fair Use Policy](https://moltsets.com/terms-of-service/).

## Enrichments

| **Plan**      | **Enrichment records every 5 hours** | **Enrichment requests every 5 hours** | **Enrichment records per week** |
| :------------ | :----------------------------------- | :------------------------------------ | :------------------------------ |
| Free          | 1k                                   | 1k                                    | 1k lifetime                     |
| \$27 / month  | 1k                                   | 5k                                    | 5k                              |
| \$97 / month  | 15k                                  | 75k                                   | 75k                             |
| \$997 / month | 180k                                 | 900k                                  | 900k                            |

## Searches

| **Plan**      | **Search records every 5 hours** | **Search requests every 5 hours** | **Search records per week** |
| :------------ | :------------------------------- | :-------------------------------- | :-------------------------- |
| Free          | 100 lifetime (5 per call max)    | 100 lifetime                      | 100 lifetime                |
| \$27 / month  | 500                              | 2.5k                              | 2.5k                        |
| \$97 / month  | 7.5k                             | 37.5k                             | 37.5k                       |
| \$997 / month | 90k                              | 450k                              | 450k                        |

## What counts as a request

Every API call counts toward the rate limit, regardless of whether it returns data. Empty results and account management calls (`get_account`, `get_billing`, `get_usage`) all count as requests.

## Check where you stand

Before assuming you've hit a wall, check your current position. `get_account`, `get_billing`, and `get_usage` are **free** — they never cost tokens.

### `get_account` — live rate-limit standing

`get_account` returns a `fair_use` object that mirrors the tables above: `enrich` and `search`, each split into `records` and `requests`, over the `5h` and `1w` windows. Each window reports `limit`, `used`, `remaining`, and `resets_at` — so you can see exactly how much headroom is left and when the window rolls over.

```json theme={null}
"fair_use": {
  "enrich": {
    "records":  { "5h": { "limit": 15000, "used": 0, "remaining": 15000, "resets_at": null } },
    "requests": { "5h": { "limit": 75000, "used": 0, "remaining": 75000, "resets_at": null } }
  },
  "search": { "records": { "5h": { "limit": 7500, "used": 0, "remaining": 7500, "resets_at": null } } }
}
```

A `resets_at` of `null` means the window hasn't started counting yet (nothing used); once you make calls it carries the ISO 8601 timestamp when that window resets.

### `get_usage` — consumption history

`get_usage` shows how many calls you've actually made over a period, broken out by day plus a `totals` block — `calls`, `with_data`, `without_data`, and `failed`. Use it to spot bursts that are pushing you toward the 5-hour caps and to confirm which runs are driving your volume.

Ask your connected agent "check my MoltSets rate-limit headroom" and it will read these for you.

## Staying within the limit

A few approaches to keep your usage within bounds:

### Spread your automations out

If you're running scheduled tasks, split them across 2–4 runs per day rather than one large burst. Smaller, more frequent runs are easier to keep under the per-second and per-minute caps.

### Use batching with pauses between batches

For high-volume operations — say, updating 10,000 leads — don't fire all requests at once. Instead:

1. Group your calls into batches of 100
2. Wait 2 seconds between each batch
3. Continue until all requests are processed

If you need help adapting your code to work within these limits, any AI coding assistant can help restructure your logic.

## Rate limit errors

When you exceed your plan's rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded."
}
```

The request is not retried automatically — your client is responsible for handling `429` responses.

## Handling rate limits

**Exponential backoff** is the recommended approach. When you receive a `429`, wait before retrying:

```javascript theme={null}
async function callWithBackoff(fn, retries = 4) {
  for (let i = 0; i < retries; i++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status !== 429 || i === retries - 1) throw err;
      await new Promise(r => setTimeout(r, Math.pow(2, i) * 200));
    }
  }
}
```

**Multiple API keys** can be used to distribute load if a single key is a bottleneck. Each key operates under its own limit, so spreading requests across keys increases effective throughput.

**Batch endpoints** where available (e.g. `linkedin_to_mobile_phone` supports up to 100 `linkedin_urls` per call) let you reduce total request count significantly.