Endpoints

Purpose	Method	URL
Synchronous scrape	GET or POST	`https://sync.scrapedrive.com/api/v1/scrape`
Submit asynchronous job	GET or POST	`https://api.scrapedrive.com:8443/api/v1/scrape/async`
Poll asynchronous job	GET	`https://api.scrapedrive.com:8443/api/v1/job/{job_id}`

The Sync endpoint returns the scraped body directly on success. Failed Sync requests return a ScrapeDrive JSON error by default; transparent_mode can instead return a target response when one exists. Async submission answers 202 with { id, status, url, status_url }. The spec text still calls the identifier job_id; the live API sends it as id, so read either name. status_url is the polling URL. Polling does not require authentication because the unguessable job id grants access to the result.

Authentication

Send api_key in the query string or request body for Sync and Async submission. Do not send it when polling an existing job.

Request parameters

Parameter	Type	Default	Rules and visible behavior
`url`	string	required	Valid HTTP or HTTPS target URL.
`proxy_pool`	enum	`datacenter`	Standard Jobs only: `datacenter` or `residential`.
`render_js`	boolean	`false`	Standard Jobs only; starts with browser rendering when `true`.
`auto`	boolean	`false`	Manages HTTP/browser acquisition and routing, progressing after failures.
`max_credits`	integer	—	Required with `auto=true`; maximum final charge from 1 to 4,294,967,295 credits.
`result_type`	enum	`html`	`html`, `page_text`, or `page_markdown`.
`device_type`	enum	`desktop`	`desktop` or `mobile` viewport and user-agent.
`screenshot`	boolean	`false`	Captures the visible viewport as a JPEG. The URL arrives in the `x-sdrive-screenshot-url` header (Sync) or in `response.headers` of the polled job (Async).
`screenshot_fullpage`	boolean	`false`	Captures the entire scrollable page.
`screenshot_selector`	string	—	Captures one element by CSS selector; errors if it is not found.
`wait_browser`	enum	—	`domcontentloaded`, `load`, or `networkidle`; browser only.
`wait_for`	string	—	CSS selector to wait for, with a 15-second selector timeout; browser only.
`wait_ms`	integer	—	Additional 0–30,000 ms after earlier waits; browser only.
`block_resources`	boolean	`true`	Skips images, CSS, and fonts in browser mode; forced off for screenshots.
`block_ads`	boolean	`true`	Skips ads and trackers in browser mode.
`proxy_country`	string	—	Standard Residential Jobs only; two-letter ISO 3166-1 code.
`custom_proxy`	string	—	Standard Jobs only; `http(s)://username:password@host:port`; replaces `proxy_pool`.
`session_number`	string	—	Standard Jobs only; a 6–32 character alphanumeric sticky-session ID.
`forward_sdrive_headers`	boolean	`false`	Forwards `sdrive-`-prefixed headers after stripping the prefix.
`transparent_mode`	boolean	`false`	Sync only. Returns a target response when the target replied but the scrape failed.
`timeout_ms`	integer	per mode	Minimum 10,000; maximum 120,000 Sync or 130,000 Async.
`webhook_url`	string	—	HTTPS callback for Async completion; ignored in Sync mode.
`custom_id`	string	—	Up to 255 characters; echoed in webhook payloads.

api_key is the authentication parameter and can be sent alongside these request parameters.

Automatic behavior

The effective request can differ from the literal fields you send:

When you choose	ScrapeDrive automatically does
Any screenshot option	Requires a browser result and loads visual resources by setting `block_resources=false`.
`render_js=true`	Starts a Standard Job with a browser engine selected by ScrapeDrive.
`auto=true`	Manages HTTP/browser selection and routing, advancing only after failure.
`custom_proxy`	Uses your proxy for the initial Standard request instead of `proxy_pool`.
Sync delivery	Caps `timeout_ms` at 120,000.

These switches affect both the result and, where documented, the credit cost. See Credits and limits.

render_js, proxy_pool, proxy_country, custom_proxy, and session_number are not accepted with auto=true. Browser waits and screenshots remain valid and require a browser-compatible Auto plan.

Sync response headers

For an admitted Sync Job, ScrapeDrive exposes settled request metadata through these CORS-readable headers:

Header	When it is present	Value
`X-Sdrive-Job-Id`	The Sync Job was admitted	Public Job identifier for history and support
`X-Sdrive-Credits`	A terminal Sync response is ready	Final settled charge; `0` on terminal failure

X-Sdrive-Credits is not a retry or execution count. It is absent from Async HTTP responses, admission rejections, and Sync timeout responses.

Public errors

Validation, rate-limit, backlog-limit, and insufficient-credit rejections are not charged.

Status	Meaning
`401`	`api_key` is missing or invalid.
`402`	The account does not have enough credits.
`422`	A required parameter is missing or a value failed validation.
`429`	The per-minute rate limit, Sync active-job limit, or Async backlog limit was exceeded.
`500`	The scrape failed. Sync returns JSON unless transparent mode can return a target response.
`504`	The Sync deadline expired without a usable target response; always a JSON error.

A job that ends without a usable target response settles at zero credits: Sync answers 500 or 504 with X-Sdrive-Credits: 0, and the polled Async job shows credits: 0 with a reason. A delivered page is charged even when the target answered 404 or 410, and even when its content is not what your workflow expected.

Source of truth

The machine-readable live contract is available at:

https://api.scrapedrive.com:8443/api/v1/spec

Use it to verify hosts, parameters, defaults, bounds, costs, and public limits when generating integrations.

API Reference