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

# Rate limits

> Every limit on calls a minute, calls at once, jobs and browser sessions by tier, the keyless limits, the headers, and what to do on a 429.

Limits rise with what the account has topped up in all: Free before the first top-up, then steps at $10, $100 and \$500. A call over a limit answers `429` and costs nothing. `GET /v1/limits` returns yours, see [Usage](https://docs.stophy.dev/account/usage.md).

## Limits

| | Free | \$10 | \$100 | \$500 |
| - | - | - | - | - |
| Calls a minute, for each endpoint | 30 | 200 | 2,000 | 8,000 |
| Job starts a minute | 5 | 20 | 100 | 500 |
| Browser session and interact starts a minute | 10 | 100 | 400 | 1,000 |
| Status, results and list reads a minute | 1,500 | 1,500 | 1,500 | 1,500 |
| Calls running at once | 2 | 10 | 70 | 250 |
| Jobs running at once | 1 | 10 | 10 | 10 |
| Jobs waiting to start | 5 | 20 | 20 | 20 |
| Browser sessions open at once | 3 | 25 | 100 | 250 |
| [Browser tasks](https://docs.stophy.dev/browser/tasks.md) open at once | 2 | 2 | 2 | 2 |

* The step counts top-ups, not the balance left. A new step applies within a minute of the top-up.
* A job is a crawl, batch, extract or agent run. A start is `POST /v1/crawl`, `/v1/batch/scrape`, `/v1/extract` or `/v1/agent`.
* A browser start is `POST /v1/browser`, a browser task or an [interact](https://docs.stophy.dev/scrape/interact.md) call.
* The calls limit counts each endpoint on its own, so busy scrapes do not use up your search limit. The other limits are shared.
* `GET /v1/concurrency-check` is free and returns `concurrency` (running now, counting the check) and `maxConcurrency`. Size your worker pool to `maxConcurrency`.

## Without a key

[Search](https://docs.stophy.dev/search/overview), [scrape](https://docs.stophy.dev/scrape/overview), [map](https://docs.stophy.dev/map/overview) and [parse](https://docs.stophy.dev/parse/overview) work with no key over HTTP and [MCP](https://docs.stophy.dev/install-mcp.md).

| Limit | Value |
| - | - |
| Calls a minute, per IP address | 10 |
| Calls a day, per IP address | 50 |
| Parse file size | 2 MB (36 MB with a key) |
| Agent signups a day, per IP address | 5 |

Which fields need a key is in [Get credentials](https://docs.stophy.dev/get-credentials.md#calls-without-a-key). `GET /v1/keyless/eligibility` returns `eligible`, `remainingToday` and `remainingThisMinute`.

## Headers

`X-RateLimit-Limit` and `X-RateLimit-Remaining` show the calls in the window. `X-RateLimit-Reset` is the reset in Unix seconds. Without a key they describe the day's allowance.

## When you go over

Read the message as well as the code. Every case is `429`.

| Code | Cause | What to do |
| - | - | - |
| `rateLimited` | Too many calls this minute | Wait `retryAfterSeconds` (also the `Retry-After` header), then retry |
| `rateLimited` | Too many calls at once | `retryAfterSeconds` is 1. Wait for a call to finish or lower concurrency. |
| `rateLimited` | Too many browser sessions or tasks open | Close one, or wait for a task to end |
| `rateLimited` | Over the signups a day | Wait `retryAfterSeconds`, or sign up at [stophy.dev/signup](https://stophy.dev/signup) |
| `freeLimit` | Over the keyless minute or day limit | Get a key at `signupUrl`, or wait `retryAfterSeconds`. A daily wait can be hours. |

Wait as long as the answer says and add random jitter. Retry rules are in [Troubleshooting](https://docs.stophy.dev/production/troubleshooting.md).


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