Async requests and polling
How BestSERP handles long searches: the timeout parameter, 202 responses with a requestId, polling GET /requests/{requestId}, and async: true.
Updated View as Markdown
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.
# 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'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
timeoutbelow your platform's limit and poll the rest.
A request still pending after 30 minutes is failed and refunded. The link resolution guide uses the same polling.