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

# Rate limits

Bigdata.com applies rate limits to keep services reliable and to share capacity fairly between users. Rate limits are separate from your credits: a rate limit is temporary and resolves itself when you wait, while running out of credits does not.

Two kinds of limits apply, and both apply at the same time:

* **[Search limits](#search-limits)** are per user. They limit how many searches you run at once and how fast you start them.
* **[API-wide traffic limits](#api-wide-traffic-limits)** are per API key and per IP address. They apply to every Bigdata API endpoint, including search and the Knowledge Graph API.

## Search limits

Each search type has its own limits:

* **Running at once:** how many searches of that type can be in progress at the same time. Some search types share this limit, as shown in the table.
* **Burst:** how many searches you can start in a quick burst after a quiet period.
* **Sustained rate:** how fast you can keep starting searches once the burst is used up.

| Search type | Endpoint | Running at once | Burst | Sustained rate |
| - | - | - | - | - |
| Fast search | `POST /v1/search` with `"search_mode": "fast"` | 30, shared with watchlist search | 60 | 10 per second |
| Smart search | `POST /v1/search` with `"search_mode": "smart"` | 15 | 30 | 1 per second |
| Watchlist search | `POST /v1/search/watchlist` | Shares the 30 with fast search | 10 | 1 every 2 seconds |
| Volume | `POST /v1/search/volume` | 20, shared with co-mentions | 300 | 10 per second |
| Co-mentions | `POST /v1/search/co-mentions/entities` and `POST /v1/search/co-mentions/topics` | Shares the 20 with volume | 30 | 5 per second |

The two co-mentions endpoints count as one search type: they share the same burst and sustained rate.

**These limits apply to your user account, not to an API key.** Searches you run through the API, the Python SDK, the MCP server and the Bigdata.com app all count toward the same limits, and so do searches that run on your behalf, such as [Batch Search](https://docs.bigdata.com/how-to-guides/search/batch_search.md), monitors and workflows. Creating more API keys does not raise your search limits.

The burst and the sustained rate are separate for each search type. Only the "running at once" limit is shared, and only where the table says so. For example, 20 fast searches and 10 watchlist searches in progress use all 30 shared slots, so the next fast or watchlist search is rejected until one of them finishes.

### How bursts work

Each search type has an allowance that holds up to the burst size. Starting a search uses one unit of it, and the allowance refills at the sustained rate, up to the burst size again. After a quiet period you can start up to the burst size in quick succession. Once the allowance is used up, you can start new searches only as fast as it refills.

For example, after a quiet period you can start 30 smart searches in quick succession. After that, you can start about one smart search per second. If you keep starting fewer than one per second, the allowance refills.

A search needs both a unit of allowance and a free slot in "running at once". The burst is not a concurrency limit: with a burst of 60 fast searches, at most 30 can be in progress at the same time. Finishing a search frees its slot, but it does not give back the allowance it used.

### Enterprise limits

Enterprise customers may have higher limits or custom limits under their agreement. Contact your account team to confirm your limits or to discuss more capacity.

## API-wide traffic limits

These limits apply across all Bigdata API endpoints, including search and the Knowledge Graph API:

| Scope | Limit |
| - | - |
| Per API key | 500 requests per minute |
| Per IP address | 1,500 requests per minute, across all API keys |

These limits are enforced approximately. They are protection thresholds, not a guaranteed throughput. Applications that send requests from the same IP address share its limit.

A request can be rejected by these limits even when it is within your search limits, and the other way round.

We recommend creating separate API keys, at least one per environment, so that traffic in your development environment does not use up the per-key limit of your production environment. Separate API keys do not separate your [search limits](#search-limits), which apply to your user account. You can create and manage your API keys in the [Developer Platform > API Keys](https://platform.bigdata.com/api-keys). See [Authentication](https://docs.bigdata.com/api-rest/authentication.md) for more details.

The Knowledge Graph API currently has only these API-wide limits. Service-specific limits for other services, including the Knowledge Graph API, are planned and will be documented here when they are introduced.

## When you reach a limit

The request is rejected with HTTP status `429 Too Many Requests`. A rejected request is not charged: it uses no credits.

When you reach a search limit, the error message says so, and the `Retry-After` header gives the number of seconds to wait before you try again:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/json

{
  "errors": [
    {
      "message": "Rate limit exceeded: too many requests in a short time. Retry after the number of seconds in the Retry-After header."
    }
  ],
  "metadata": {
    "request_id": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef",
    "timestamp": "2026-10-15T09:07:39.882000+00:00"
  }
}
```

| Response | What to do |
| - | - |
| `429` with a `Retry-After` header | Wait at least that many seconds, then retry. Retrying sooner is rejected again. |
| `429` without a `Retry-After` header | Back off exponentially: wait 1 second, then 2, then 4, and stop after a few attempts. |
| `429` with the message "You've used up your credits." | Stop retrying. This is not a rate limit, and waiting does not help: you need more credits. See [Pricing](https://docs.bigdata.com/getting-started/bigdata_pricing.md). |

Add a small random delay to each retry, so that requests rejected together do not all come back at the same moment. A retry can still be rejected if your other searches keep using the allowance, so limit the number of attempts and report an error when they run out.

Some Bigdata.com clients already retry for you:

* **[Batch Search](https://docs.bigdata.com/how-to-guides/search/batch_search.md)** waits for `Retry-After` and retries each search a few times. A search that is still rejected appears in the output file with `status` set to `error`.
* **The MCP server** retries a rejected search once when the wait is short. If the search is still rejected, the search tool returns an error that tells the assistant how long to wait. See [MCP error codes](https://docs.bigdata.com/mcp-reference/mcp-error-codes.md#search-rate-limit).

## Best practices

* **Control parallelism and pace separately.** A worker pool limits how many searches run at once. A scheduler limits how fast they start. Continuous workloads need both.
* **Coordinate everything that runs as the same user.** All applications, workers and API keys of one user share the search limits. If several processes or servers search as the same user, give them a shared queue or rate limiter.
* **Count retries as traffic.** Send retries through the same scheduler as first attempts. Retry in one layer only, so that application and SDK retries do not multiply.
* **Avoid duplicate work.** Reuse results when your freshness requirements allow it, and request only the data you need.
* **Use [Batch Search](https://docs.bigdata.com/how-to-guides/search/batch_search.md) for large sets of queries.** You upload all your queries in one file, and Bigdata.com runs them at a pace that stays within your limits. The rate limits can make a batch take longer to complete.
* **Keep AI assistant workloads bounded.** If you use Bigdata.com through an AI assistant or an agent framework, configure it to run searches one or two at a time instead of many in parallel, and to wait when it is told to.

### Python example: retrying a search

This example waits for `Retry-After`, adds a small random delay, and stops after five attempts. It stops at once when you are out of credits, and it raises any other HTTP error.

Install the dependency:

```bash theme={null}
python -m pip install requests
```

Save the following as `retry_example.py`:

```python theme={null}
import random
import time

import requests

SEARCH_URL = "https://api.bigdata.com/v1/search"
MAX_ATTEMPTS = 5
MAX_WAIT_SECONDS = 60


def retry_delay(response, attempt):
    """Seconds to wait before the next attempt."""
    retry_after = response.headers.get("Retry-After", "").strip()
    if retry_after.isdigit():
        return min(int(retry_after), MAX_WAIT_SECONDS)
    return min(2**attempt, MAX_WAIT_SECONDS)  # No Retry-After: 1, 2, 4, 8 seconds


def search_with_retry(api_key, payload, before_attempt=None):
    for attempt in range(MAX_ATTEMPTS):
        if before_attempt:
            before_attempt()  # Optional shared pacing, retries included

        response = requests.post(
            SEARCH_URL,
            headers={"X-API-KEY": api_key},
            json=payload,
            timeout=(10, 120),
        )
        if response.status_code != 429:
            response.raise_for_status()
            return response.json()

        out_of_credits = "used up your credits" in response.text.lower()
        if out_of_credits or attempt == MAX_ATTEMPTS - 1:
            response.raise_for_status()  # Raises requests.HTTPError

        time.sleep(retry_delay(response, attempt) + random.uniform(0, 0.5))
```

With `BIGDATA_API_KEY` set in your environment and a valid search request body in `payload`:

```python theme={null}
import os

from retry_example import search_with_retry

result = search_with_retry(os.environ["BIGDATA_API_KEY"], payload)
```

Adjust the connection and read timeouts, `(10, 120)` seconds here, to your workload. Network errors are raised to the caller.

### Python example: running searches in parallel

For continuous workloads, combine the retry helper with a shared pacer and a fixed-size worker pool.

This example starts at most **5 fast searches per second** and runs at most **4 at the same time**. These are example settings, well within the fast search limits, not the limits themselves. Retries go through the same pacer as first attempts.

Save this next to `retry_example.py`, and call `run_searches(api_key, payloads)` with a list of valid fast search request bodies:

```python theme={null}
import threading
import time
from concurrent.futures import ThreadPoolExecutor

from retry_example import search_with_retry


def run_searches(api_key, payloads, requests_per_second=5, workers=4):
    if requests_per_second <= 0 or workers < 1:
        raise ValueError("Request rate and worker count must be positive")
    lock = threading.Lock()
    next_start = 0.0

    def pace():
        nonlocal next_start
        with lock:
            time.sleep(max(0, next_start - time.monotonic()))
            next_start = time.monotonic() + 1 / requests_per_second

    def run(payload):
        return search_with_retry(api_key, payload, before_attempt=pace)

    with ThreadPoolExecutor(max_workers=workers) as pool:
        return list(pool.map(run, payloads))
```

Each worker runs one search at a time, including its retry waits. The pacer spaces out the starts evenly, so this example never bursts. It returns the results in the order of `payloads`, and if a search fails, it raises that search's error.

The pacer and the pool only control the searches of one `run_searches` call. If several calls, processes or servers search as the same user, share one limiter between them. Choose settings that fit your search type, your limits and your other traffic, and keep the [API-wide traffic limits](#api-wide-traffic-limits) in mind. For large sets of queries, use [Batch Search](https://docs.bigdata.com/how-to-guides/search/batch_search.md).

## Getting help

If your searches are still rejected after following these practices, contact support with the request IDs from the error responses, the search type, the approximate times, and how fast and how many searches at once you send. Do not include your API key.

For workloads that consistently need more capacity, contact your account team about [enterprise limits](#enterprise-limits).


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