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 timeout below 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.