This guide follows the current Scrapingbypass API documentation: V2s uses the same parameters as V2 but adds stream response support. Before production use, confirm the latest settings in the official docs and your API console.
Decision Flow
To choose between V1, V2, and V2s, ask two questions: does the target require challenge handling, and does the response need to be streamed? V2s is not a separate challenge type. It is V2 with stream response.
Step 1: Start with V1 for simple 403 cases
- The page opens in a normal browser.
- Your code receives 403.
- There is no
cf-mitigated: challengeresponse header. - There is no Turnstile widget during form submission.
- You do not need server-side session reuse.
If these conditions match, V1 is usually the simplest starting point.
Step 2: Switch to V2 for JS Challenge or Turnstile
If the first page load returns a Cloudflare challenge, or the response includes cf-mitigated: challenge, use V2. If a form triggers Turnstile, use V2 with x-cb-sitekey and place [cf_token] where the target API expects the token.
curl --request POST --url "https://api.scrapingbypass.com/api/submit" --header "x-cb-apikey: YOUR_APIKEY" --header "x-cb-host: target.com" --header "x-cb-version: 2" --header "x-cb-proxy: http://user:pass@proxy-host:port" --header "x-cb-sitekey: 0x4AAAA..." --header "content-type: application/json" --data '{"turnstileToken":"[cf_token]"}'Step 3: Use V2s when V2 needs streaming
If the request still needs V2 behavior but the response is large or long-running, switch to V2s. Common examples include ZIP/PDF downloads, CSV exports, large reports, and workflows that write the response to disk while downloading.
curl --request GET --url "https://api.scrapingbypass.com/download/report.csv" --header "x-cb-apikey: YOUR_APIKEY" --header "x-cb-host: target.com" --header "x-cb-version: 2s" --header "x-cb-proxy: http://user:pass@proxy-host:port" --output report.csvQuick Decision Table
| Signal | Use | Why |
|---|---|---|
| Browser works, code gets 403, no challenge | V1 | Lightweight bypass |
cf-mitigated: challenge appears | V2 | JS Challenge handling |
| Form submission triggers Turnstile | V2 | Requires x-cb-sitekey and [cf_token] |
| V2 scenario plus large file or long response | V2s | Needs stream response |
| Concurrent session reuse | V2/V2s + part | Use x-cb-part to separate sessions |
Troubleshooting tips
- If V1 fails with a challenge signal, switch to V2.
- If V2 works but large downloads are unstable, use
x-cb-version: 2s. - For V2s, make sure your HTTP client reads the response as a stream instead of loading the whole body into memory.
- For multi-threaded jobs, avoid sharing the same
x-cb-partacross all workers.