# Async requests and polling

> How BestSERP handles long searches: the timeout parameter, 202 responses with a requestId, polling GET /requests/{requestId}, and async: true.

Source: https://bestserp.com/docs/async (updated 2026-11-14)

A request waits up to `timeout` seconds (default 60, at most 120). If the search is not finished by then, or you sent `"async": true`, the API answers `202` with a `requestId` and a `Location` header. Poll `GET /requests/{requestId}` until it answers `200` with the same body a synchronous call returns. Polling is free and not rate limited.

**cURL**

```bash
# 1. Ask for an async answer
curl -X POST 'https://api.bestserp.com/search' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"q": "best running shoes", "async": true}'
# -> 202 {"requestId": "...", "status": "pending", "pollUrl": "/requests/..."}

# 2. Poll until it answers 200
curl 'https://api.bestserp.com/requests/REQUEST_ID' -H 'X-API-KEY: YOUR_API_KEY'
```

**Python**

```python
import time

import requests

API, KEY = "https://api.bestserp.com", "YOUR_API_KEY"
r = requests.post(f"{API}/search", headers={"X-API-KEY": KEY}, json={"q": "best running shoes", "async": True})
while r.status_code == 202:
    time.sleep(1.5)
    r = requests.get(f"{API}/requests/{r.json()['requestId']}", headers={"X-API-KEY": KEY})
r.raise_for_status()
print(r.json()["organic"][0])
```

## When to use it

- **Batch jobs**: submit many searches with `async: true`, then collect them. Credits are reserved when a request is accepted.
- **Short HTTP timeouts** (serverless functions, proxies): set `timeout` below your platform's limit and poll the rest.

A request still pending after 30 minutes is failed and refunded. The [link resolution](https://bestserp.com/docs/link-resolution) guide uses the same polling.
