> ## 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

> Stophy limits calls a minute, calls at once, jobs and browser sessions by tier. Without an API key, 10 calls a minute and 50 a day per IP address.

Stophy limits how many calls you can make in a minute and how many can run at once. The limits depend on your tier: `free` until your first top-up, then `paid`. `GET /v1/limits` returns yours. A call over a limit answers `429` and costs nothing.

## Limits

| | `free` | `paid` |
| - | - | - |
| Calls a minute, for each endpoint | 100 | 600 |
| Job starts a minute | 10 | 100 |
| Browser session and interact starts a minute | 10 | 100 |
| Status, results and list reads a minute | 1,500 | 1,500 |
| Calls running at once | 2 | 10 |
| Crawls, batches, extracts and agent runs running at once | 1 | 10 |
| Jobs waiting to start | 5 | 20 |
| Browser sessions open at once | 3 | 10 |

A job start is `POST /v1/crawl`, `/v1/batch/scrape`, `/v1/extract` or `/v1/agent`. A browser start is `POST /v1/browser`, a [browser task](https://docs.stophy.dev/browser/tasks.md) or an [interact](https://docs.stophy.dev/scrape/interact.md) call. The calls limit counts each endpoint on its own, so a busy scrape does not use up your search limit. The three other limits are shared by every call of their kind.

Without an API key you can call [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), over HTTP and [MCP](https://docs.stophy.dev/mcp/keyless.md), up to 10 calls a minute and 50 calls a day per IP address, with no paging. Scrape with a [parser](https://docs.stophy.dev/scrape/prebuilt-parsers) works without an API key when the parser is marked `keyless: true`. Crawl, batches, extract, agent, browsers and monitors need an API key. See [API keys](https://docs.stophy.dev/account/api-keys.md). A first top-up lifts you to the `paid` limits.

## Read your limits

`GET /v1/limits` returns your tier, limits and what is left this minute. It counts as one call. On the `free` tier, `paidLimits` shows the limits you get after a top-up.

```bash theme={null}
curl https://api.stophy.dev/v1/limits -H "Authorization: Bearer $STOPHY_API_KEY"
```

```json theme={null}
{
  "success": true,
  "data": {
    "tier": "paid",
    "rateLimit": { "limitPerMinute": 600, "remaining": 597, "resetsAt": "2026-11-17T17:44:00.000Z" },
    "perMinute": { "calls": 600, "jobs": 100, "interact": 100, "reads": 1500 },
    "concurrency": { "limit": 10, "inUse": 1 },
    "jobsAtOnce": 10,
    "queuedJobs": 20,
    "sessionsAtOnce": 10,
    "paidLimits": null
  },
  "costUsd": 0
}
```

This real response is cut to the limit fields. See [Usage](https://docs.stophy.dev/account/usage.md) for every field.

## Check calls running at once

`GET /v1/concurrency-check` is free. It returns how many of your calls are running and how many can run at once.

```bash cURL theme={null}
curl https://api.stophy.dev/v1/concurrency-check \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/concurrency-check", {
  headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}` },
});
const { concurrency, maxConcurrency } = await response.json();
console.log(`${concurrency} of ${maxConcurrency} calls running`);
```

```python Python theme={null}
import os

import requests

response = requests.get(
    "https://api.stophy.dev/v1/concurrency-check",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
)
body = response.json()
print(body["concurrency"], "of", body["maxConcurrency"], "calls running")
```

```json theme={null}
{
  "success": true,
  "concurrency": 1,
  "maxConcurrency": 10,
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "07ab5f1a-453f-4771-ae80-fc511883eb9f"
}
```

`concurrency` counts the check itself. Size your worker pool to `maxConcurrency`. `GET /v1/team/queue-status` shows your running and waiting jobs. See [Usage and logs](https://docs.stophy.dev/production/usage-and-logs.md).

## Check calls without an API key

`GET /v1/keyless/eligibility` needs no API key. It says whether your IP address can still make calls without an API key, and how many it has left.

```bash theme={null}
curl https://api.stophy.dev/v1/keyless/eligibility
```

```json theme={null}
{
  "success": true,
  "eligible": true,
  "remainingToday": 50,
  "remainingThisMinute": 10,
  "costUsd": 0
}
```

## Headers

Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`, the Unix time in seconds when the window resets. Without an API key they count the day's calls. These headers came from a real scrape without an API key.

```text theme={null}
x-ratelimit-limit: 50
x-ratelimit-remaining: 48
x-ratelimit-reset: 1794960000
```

## When you go over

| Code | Status | Cause | What to do |
| - | - | - | - |
| `rateLimited` | `429` | Too many calls this minute | Wait `retryAfterSeconds`, which is also the `Retry-After` header, then retry |
| `rateLimited` | `429` | Too many calls running at once | The answer says so and `retryAfterSeconds` is 1. Wait for a call to finish, or lower your concurrency. |
| `rateLimited` | `429` | Too many browser sessions open | The answer says how many are open. Close one to open another. |
| `freeLimit` | `429` | The 10 calls a minute or 50 a day without an API key are used | Get an API key at `signupUrl`, or wait `retryAfterSeconds`. A daily wait can be hours. |
| `rateLimited` | `429` | Five signups from one IP address in a day | Wait `retryAfterSeconds`, or sign up at [stophy.dev/signup](https://stophy.dev/signup) |

A `rateLimited` answer looks like this. This is the shape from the [API reference](https://docs.stophy.dev/api-reference/errors.md), and the numbers are an example.

```json theme={null}
{
  "success": false,
  "error": "Too many requests this minute. Send the call again after the number of seconds in retryAfterSeconds.",
  "code": "rateLimited",
  "retryable": true,
  "retryAfterSeconds": 12
}
```

Before you retry, wait as long as the answer says, and add random jitter to the wait. [Troubleshooting](https://docs.stophy.dev/production/troubleshooting.md) has a retry loop.

## Related

* [Usage](https://docs.stophy.dev/account/usage.md)
* [API keys](https://docs.stophy.dev/account/api-keys.md)
* [Timeouts](https://docs.stophy.dev/production/timeouts.md)
* [Troubleshooting](https://docs.stophy.dev/production/troubleshooting.md)


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