Zenrows API
Zenrows is web data infrastructure for agents and applications. Three HTTP surfaces are described here: Fetch and Extract: one synchronous request per page,…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
Zenrows is web data infrastructure for agents and applications. Three HTTP surfaces are described here:
- Fetch and Extract: one synchronous request per page, at
https://api.zenrows.com/v1/. Authentication is theapikeyquery parameter. - Crawl: collect the URLs behind one start page, at
https://api.zenrows.com/v1/crawls. Authentication is theX-API-Keyheader or theapikeyquery parameter. - Batch: asynchronous jobs of up to 100,000 URLs, at
https://async.api.zenrows.com/v1. Authentication is theX-API-Keyheader.
Browser is not described here because it is not HTTP: you connect Puppeteer or Playwright to a WebSocket endpoint. See https://docs.zenrows.com/browser-sessions/introduction.
Cost. A request costs 1 credit, 5 with JavaScript rendering, 10 with premium proxies, 25 with both, and 1 to 25 under mode=auto. Failed requests are not charged, except target 404 and 410 answers, which are billed like a success. The free tier is 5,000 credits a month, no card.
Versioning and deprecation. The version is in the URL path (/v1, the only version so far). Inside a version Zenrows only adds: new endpoints, optional parameters, response fields and headers. Nothing is removed or changed. Retiring a version is announced at least twelve months ahead, and every response from a deprecated version carries the Deprecation (RFC 9745) and Sunset (RFC 8594) headers. Policy: https://docs.zenrows.com/api-versioning.
Getting a key without a human. POST https://app.zenrows.com/api/agent/signup returns a usable key; the spec is at https://www.zenrows.com/auth.md and a setup playbook at https://www.zenrows.com/SKILL.md.
Endpoints 50
Fetch
- GETFetch a page
/?url=https://www.scrapingcourse.com/ecommerce/Retrieve a URL through Zenrows and return its content. The same operation covers Extract (extract=auto or css_extractor), format conversion (response_type),… - PUTFetch a page with a PUT
/?url=https://www.scrapingcourse.com/ecommerce/Send a PUT to the target through Zenrows. Takes the same query parameters as fetchPage; the request body is forwarded to the target as is, and the response… - POSTFetch a page with a POST
/?url=https://www.scrapingcourse.com/ecommerce/Send a POST to the target through Zenrows. Takes the same query parameters as fetchPage; the request body is forwarded to the target as is, and the response…
Extract
- GETList the domains Extract serves
/extract/domainsEvery domain Extract can handle right now. A domain in this list is one you can send extract=auto to; a domain missing from it answers REQS007. Costs no… - GETList the domains your account submitted
/extract/prepared-domainsEvery domain this account has submitted for preparation, with the monthly allowance alongside it. This lists what you submitted, not every domain Extract… - POSTAsk for a domain to be prepared for Extract
/extract/prepared-domainsSubmit a domain for preparation, within a monthly allowance. The submission is accepted immediately and works through discovery, preparation and verification,… - GETRead the monthly preparation allowance
/extract/prepared-domains/allowanceHow many domains this account can still ask to have prepared this month. Costs no credits. Documented at https://docs.zenrows.com/extract/endpoints. - GETTrack a domain's preparation
/extract/prepared-domains/:domainHow far a submission has got. Branch on status (preparing, ready, failed); state is the finer-grained step. Costs no credits. Documented at…
Crawl
- GETList your crawls
/crawlsYour crawls, newest first, without their results. Documented at https://docs.zenrows.com/crawl/endpoints#list-your-crawls. - POSTStart a crawl
/crawlsStart a crawl from one URL and return at once with 202 Accepted, the crawl in the body and its path in the Location header. Each page it opens is one Fetch… - GETRead a crawl and its results
/crawls/:crawl_idThe crawl, its coverage so far and one page of results. While it runs, next_cursor is never null: read again with the same cursor to get only the new URLs.… - GETDownload all results
/crawls/:crawl_id/downloadEvery result as one NDJSON file named {crawl_id}.jsonl, one JSON object per line. Each line has the url; with output_format, also content_status and, once… - GETRead one page's HTML
/crawls/:crawl_id/contents/:content_idThe HTML of one kept page, for a crawl started with output_format. Take the path from the result's content_url. Documented at… - POSTStop a crawl
/crawls/:crawl_id/stopStop a running crawl. No new page is fetched; pages already being fetched finish, are billed and are kept for up to 10 minutes. Read the crawl until…
Batch
- GETList batch jobs
https://async.api.zenrows.com/v1/jobsNewest first. Optional status / type filters. - POSTCreate a batch job (many URLs in one request)
https://async.api.zenrows.com/v1/jobsValidates inputs and authenticates the caller, then persists the job, its first run, and (for small submits) all tasks before returning. Validation failures… - GETRead a job and its latest run
https://async.api.zenrows.com/v1/jobs/:job_id - DELETEDelete a job and all its artifacts (asynchronous)
https://async.api.zenrows.com/v1/jobs/:job_idFlips the job to deleted immediately and flips the latest run to deleted if it was in-flight (so no new tasks get picked up), then returns 202. The job's… - POSTAdd URLs to an open job
https://async.api.zenrows.com/v1/jobs/:job_id/tasksValid only when the job is open AND its latest run is run_sequence == 1 AND last_batch_received == false. Targets the latest (initial) run. Closed jobs and… - POSTClose an open job (no more tasks coming)
https://async.api.zenrows.com/v1/jobs/:job_id/closeFlips job.status from open to closed and sets the initial run's last_batch_received = true, the same as an addBatchTasks call with last_batch: true on its… - POSTStop the current run
https://async.api.zenrows.com/v1/jobs/:job_id/stopSynchronously transitions latest_run.status from running or pending to terminal stopped. No new tasks are picked up; tasks already in flight may still finish… - POSTCancel the current run
https://async.api.zenrows.com/v1/jobs/:job_id/cancelUser-facing alias for /stop. Same semantics, same terminal stopped state, same response shape. - POSTPause the current run
https://async.api.zenrows.com/v1/jobs/:job_id/pauseReversible suspend of the latest run. Sets latest_run.pause_state = paused; no new tasks start. The run's status (running / pending) is unchanged: pause is… - POSTResume a paused run
https://async.api.zenrows.com/v1/jobs/:job_id/resumeInverse of /pause. Sets latest_run.pause_state = active; the remaining tasks start again. Idempotent on already-active runs. - POSTStart a new run (full replay or partial retry of the previous run)
https://async.api.zenrows.com/v1/jobs/:job_id/rerunTwo modes share this endpoint, picked by the optional ?status= filter: Full rerun (no status). Replays every task from the previous run into a fresh new run.… - PUTReplace the schedule of a scheduled job
https://async.api.zenrows.com/v1/jobs/:job_id/scheduleWholesale replaces the schedule on a type: scheduled job. The body is the same BatchJobSchedule shape used at submit. Only valid on scheduled jobs: regular… - POSTPause or resume a scheduled job
https://async.api.zenrows.com/v1/jobs/:job_id/schedule/stateFlips schedule_state between active and paused. Only valid on type: scheduled jobs. While paused, scheduled fires are skipped; resuming makes the next… - GETRead the current webhook config
https://async.api.zenrows.com/v1/jobs/:job_id/webhookReturns the job's webhook config or 404 when none is set. The same shape is also surfaced inline on GET /v1/jobs/{id} via the webhook field. - PUTReplace the webhook config
https://async.api.zenrows.com/v1/jobs/:job_id/webhookReplaces the webhook config wholesale. Both url and signature are required: no defaulting at the mutate boundary (preventing a PUT {"url":"..."} from silently… - DELETEClear the webhook config
https://async.api.zenrows.com/v1/jobs/:job_id/webhookIdempotent: returns 204 whether or not a webhook was configured. After this call no further run.completed / run.failed deliveries are sent for this Job:… - GETList runs of a job (newest first)
https://async.api.zenrows.com/v1/jobs/:job_id/runs - GETGet one run by id
https://async.api.zenrows.com/v1/jobs/:job_id/runs/:run_id - DELETEDelete one run and its artifacts (asynchronous)
https://async.api.zenrows.com/v1/jobs/:job_id/runs/:run_idAsync hard-delete of a single run. Synchronously: flips the run to deleted and (if this was the latest run) makes the next-newest non-deleted run the job's… - GETPage through per-task results for the latest run of a job
https://async.api.zenrows.com/v1/jobs/:job_id/resultsShortcut for the latest run; see getBatchRunResults for the explicit form. - GETPage through per-task results for a specific run
https://async.api.zenrows.com/v1/jobs/:job_id/runs/:run_id/results - GETFetch the scraped content for a task in the latest run
https://async.api.zenrows.com/v1/jobs/:job_id/tasks/:task_id/contentLatest-run shortcut. See getBatchRunTaskContent for explicit-run form. - GETFetch the scraped content for a task in a specific run
https://async.api.zenrows.com/v1/jobs/:job_id/runs/:run_id/tasks/:task_id/content - GETGet the attempt history for a task in the latest run
https://async.api.zenrows.com/v1/jobs/:job_id/tasks/:task_id/history - GETGet the attempt history for a task in a specific run
https://async.api.zenrows.com/v1/jobs/:job_id/runs/:run_id/tasks/:task_id/history - GETList the account's HMAC key metadata
https://async.api.zenrows.com/v1/hmac/keysReturns kid + created_at for whichever slots are populated (active and/or candidate). NEVER returns secret material: the only chance to capture a secret is… - POSTGenerate the initial key, or stage a candidate
https://async.api.zenrows.com/v1/hmac/keys/rotateUnified rotation endpoint: No active key yet → generates the account's first active key. Active exists, no candidate → generates a candidate for phased… - DELETEDiscard the pending candidate
https://async.api.zenrows.com/v1/hmac/keys/rotateDrops the candidate slot. Idempotent: returns 204 even when no candidate is present. - POSTPromote the candidate to active
https://async.api.zenrows.com/v1/hmac/keys/rotate/finalizePromotes the pending candidate to active; the prior active is discarded. Returns the new active's metadata; no secret. Returns 409 no_candidate if nothing is… - POSTSend a synthetic test event to a webhook URL
https://async.api.zenrows.com/v1/webhook/testSynchronous one-shot dispatch of a webhook.test event against a caller-supplied URL. Independent of any job: body carries the same { url, signature } shape as… - POSTCreate a CSV upload slot
https://async.api.zenrows.com/v1/job_inputsAllocates a file_input_id, persists the parse spec, and returns a presigned PUT URL the caller uploads the CSV body to. The slot lives 24 h; subsequent POST… - POSTStart an async results export
https://async.api.zenrows.com/v1/jobs/:job_id/runs/:run_id/exportsKicks off an async zip of every task body in the run for short-term download. Returns an export_id immediately; poll getBatchExport for status and the… - GETPoll a results export
https://async.api.zenrows.com/v1/jobs/:job_id/runs/:run_id/exports/:export_idReturns the current status and (on completed) a freshly presigned download_url, valid for 2 hours. The URL is signed on every call, so callers may stash the…
Account
- GETRead the plan behind the key
/subscriptions/self/detailsReturn the calling key's plan: credit allowance, credits used, and the concurrency it is allowed. Use it to budget before a large run.
Onboarding
- POSTGet an API key for your agent, no signup required
https://app.zenrows.com/api/agent/signupStart using Zenrows from your agent without signing up. This call returns a working API key straight away: no account setup, no login, no payment details. The… - GETCheck whether a person has claimed this account
https://app.zenrows.com/api/agent/accountReport the claim state of an account created by createAgentAccount. Claiming does not rotate the key, so an agent keeps working across it; this is how it…
API details
- Base URL
https://api.zenrows.com/v1- Authentication
- An API key in the apikey query parameter
An API key in the X-API-Key header - Operations
- 50 operations on 40 pathsGET 24POST 19DELETE 4PUT 3
- Main resources
- Batch 33Crawl 6Extract 5Fetch 3Onboarding 2Account 1
- Response formats
application/jsonapplication/problem+jsontext/htmltext/markdown- Description format
- OpenAPI 3.1.0, API version
1.0.0 - Links
- Documentation · OpenAPI document · Terms of service · Support
- Listed from
- Zenrows's published OpenAPI description
How to test the Zenrows API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Zenrows API collection, without the publisher's secrets.
- Add your credentialsThis API uses an API key in the apikey query parameter. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Fetch a page” (GET /?url=https://www.scrapingcourse.com/ecommerce/), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Zenrows API?
Zenrows is web data infrastructure for agents and applications. Three HTTP surfaces are described here: Fetch and Extract: one synchronous request per page,… It is listed under Developer tools and has 50 endpoints.
Who publishes the Zenrows API?
It is listed from Zenrows's public API description (an OpenAPI document), not published by Zenrows on Swastik Codes. Anyone who controls zenrows.com can claim the profile by adding a DNS TXT record.
What is the base URL of the Zenrows API?
Requests go to https://api.zenrows.com/v1. Endpoint paths are added to this base URL.
How do I authenticate with the Zenrows API?
It accepts 2 methods: an API key in the apikey query parameter; an API key in the X-API-Key header.
How many endpoints does the Zenrows API have?
50 operations on 40 paths (24 GET, 19 POST, 4 DELETE, 3 PUT). The largest groups are Batch, Crawl, Extract, Fetch.
Is forking the Zenrows API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.