Your first request
Understand submission, polling, and result retrieval.
| Step | HTTP | Expected response | What to do |
|---|---|---|---|
| Submit | POST /api/v1/data/requests | 202 with an id; a cache hit may already be completed | Save id and the idempotency key. |
| Poll | GET /api/v1/data/requests/{id} | 200 with pending, running, or solving_captcha while active | Use exponential backoff with jitter and an overall deadline. |
| Complete | same poll endpoint | 200, completed | Only now request the result. |
| Retrieve | GET /api/v1/data/requests/{id}/result | 200 | Validate html, text, or structured data. |
| Terminal failure | same poll endpoint | failed or cancelled | Inspect the public error fields; resubmit only when appropriate. |
The request states are pending, running, solving_captcha, completed, failed, and cancelled. Polling can skip intermediate states; CAPTCHA handling is not a required stage. A result request before completion returns 409 RESULT_NOT_READY; an expired retained result returns 410 RESULT_EXPIRED.
Use Idempotency-Key on submission so a network retry does not accidentally create duplicate work. Generate it before the first POST, keep it with the exact body for retries, and use a new key for a new logical request. Do not assume that a submitted request is complete, and do not treat a non-2xx response as a result payload.
Last updated on