curl --request POST \
--url https://async.api.zenrows.com/v1/jobs \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '{}'import requests
url = "https://async.api.zenrows.com/v1/jobs"
payload = {}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch('https://async.api.zenrows.com/v1/jobs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://async.api.zenrows.com/v1/jobs';
const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://async.api.zenrows.com/v1/jobs"
payload := strings.NewReader("{}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://async.api.zenrows.com/v1/jobs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}require 'uri'
require 'net/http'
url = URI("https://async.api.zenrows.com/v1/jobs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{}"
response = http.request(request)
puts response.read_bodyHttpResponse<String> response = Unirest.post("https://async.api.zenrows.com/v1/jobs")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{}")
.asString();{
"job_id": "<string>",
"status": "open",
"accepted_tasks": 123,
"latest_run": {
"run_id": "<string>",
"job_id": "<string>",
"run_sequence": 2,
"status": "running",
"stats": {
"total": 123,
"completed": 123,
"successful": 123,
"failed": 123,
"failure_reasons": {
"blocked": 9,
"gateway_error": 4
},
"spend": {
"credits": 1,
"cost": 1
}
},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"trigger": "manual",
"last_batch_received": true,
"pause_state": "active",
"ingest_status": "pending",
"failure_reason": "insufficient_credits",
"failure_detail": "Subscription has no credit available."
},
"webhook": {
"url": "<string>",
"signature": true
}
}{
"job_id": "<string>",
"status": "open",
"accepted_tasks": 123,
"latest_run": {
"run_id": "<string>",
"job_id": "<string>",
"run_sequence": 2,
"status": "running",
"stats": {
"total": 123,
"completed": 123,
"successful": 123,
"failed": 123,
"failure_reasons": {
"blocked": 9,
"gateway_error": 4
},
"spend": {
"credits": 1,
"cost": 1
}
},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"trigger": "manual",
"last_batch_received": true,
"pause_state": "active",
"ingest_status": "pending",
"failure_reason": "insufficient_credits",
"failure_detail": "Subscription has no credit available."
},
"webhook": {
"url": "<string>",
"signature": true
}
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"instance": "<string>",
"invalid_tasks": [
{
"index": 123,
"reason": "malformed_url",
"value": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"instance": "<string>",
"invalid_tasks": [
{
"index": 123,
"reason": "malformed_url",
"value": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"instance": "<string>",
"invalid_tasks": [
{
"index": 123,
"reason": "malformed_url",
"value": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"instance": "<string>",
"invalid_tasks": [
{
"index": 123,
"reason": "malformed_url",
"value": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"instance": "<string>",
"invalid_tasks": [
{
"index": 123,
"reason": "malformed_url",
"value": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"instance": "<string>",
"invalid_tasks": [
{
"index": 123,
"reason": "malformed_url",
"value": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"instance": "<string>",
"invalid_tasks": [
{
"index": 123,
"reason": "malformed_url",
"value": "<string>"
}
]
}Create a batch job (many URLs in one request)
Validates inputs and authenticates the caller, then persists
the job, its first run, and (for small submits) all tasks
before returning. Validation failures (4xx) create nothing. A
503 from a temporary failure usually creates nothing
either, but a late-stage failure can leave the job visible
with its run already stopped: safe to DELETE. A 503
that came before the job was created gives the
Idempotency-Key back, so the same key works on retry. A
503 after the job was created keeps the key (a retry under
it is 409 idempotency_key_conflict): check GET /v1/jobs
before you resend with a fresh key.
Submissions under 10,000 inline tasks return 201 Created
with the task rows already in place: results are immediately
queryable via GET /v1/jobs/{id}/results.
Submissions at or above 10,000 inline tasks are processed
off the request path and return 202 Accepted: accepted_tasks
is the final validated count, but task rows stream into
storage over the following seconds (large submissions can take
longer). GET /v1/jobs/{id}/results returns only the rows
written so far until ingest completes; the run’s stats.total
is correct from the start so completion polling
(stats.completed >= stats.total) is reliable from the first
response. While ingestion is in progress,
POST /v1/jobs/{id}/tasks on an open job returns 409:
retry it once results pages fill out. The run’s
ingest_status field reports the ingest state: poll
GET /v1/jobs/{id} until latest_run.ingest_status is
done to know every task row is visible.
Limits (defaults; an account can have its own): at most
100,000 tasks per submit, 3 active (non-terminal) regular
jobs and 5 scheduled jobs per account. An open job holds an
active slot until it is closed; an idle open job is closed
automatically after 48 hours. A rate schedule must fire at
most once every 60 minutes. Going over a job cap returns
429 quota_exceeded; going over the task limit or the
schedule interval returns 400 invalid_argument. A request
refused by one of these checks gives its Idempotency-Key
back: once you free a slot (or fix the request), retry with
the same key.
curl --request POST \
--url https://async.api.zenrows.com/v1/jobs \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '{}'import requests
url = "https://async.api.zenrows.com/v1/jobs"
payload = {}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch('https://async.api.zenrows.com/v1/jobs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://async.api.zenrows.com/v1/jobs';
const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://async.api.zenrows.com/v1/jobs"
payload := strings.NewReader("{}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://async.api.zenrows.com/v1/jobs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}require 'uri'
require 'net/http'
url = URI("https://async.api.zenrows.com/v1/jobs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{}"
response = http.request(request)
puts response.read_bodyHttpResponse<String> response = Unirest.post("https://async.api.zenrows.com/v1/jobs")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{}")
.asString();{
"job_id": "<string>",
"status": "open",
"accepted_tasks": 123,
"latest_run": {
"run_id": "<string>",
"job_id": "<string>",
"run_sequence": 2,
"status": "running",
"stats": {
"total": 123,
"completed": 123,
"successful": 123,
"failed": 123,
"failure_reasons": {
"blocked": 9,
"gateway_error": 4
},
"spend": {
"credits": 1,
"cost": 1
}
},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"trigger": "manual",
"last_batch_received": true,
"pause_state": "active",
"ingest_status": "pending",
"failure_reason": "insufficient_credits",
"failure_detail": "Subscription has no credit available."
},
"webhook": {
"url": "<string>",
"signature": true
}
}{
"job_id": "<string>",
"status": "open",
"accepted_tasks": 123,
"latest_run": {
"run_id": "<string>",
"job_id": "<string>",
"run_sequence": 2,
"status": "running",
"stats": {
"total": 123,
"completed": 123,
"successful": 123,
"failed": 123,
"failure_reasons": {
"blocked": 9,
"gateway_error": 4
},
"spend": {
"credits": 1,
"cost": 1
}
},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"trigger": "manual",
"last_batch_received": true,
"pause_state": "active",
"ingest_status": "pending",
"failure_reason": "insufficient_credits",
"failure_detail": "Subscription has no credit available."
},
"webhook": {
"url": "<string>",
"signature": true
}
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"instance": "<string>",
"invalid_tasks": [
{
"index": 123,
"reason": "malformed_url",
"value": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"instance": "<string>",
"invalid_tasks": [
{
"index": 123,
"reason": "malformed_url",
"value": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"instance": "<string>",
"invalid_tasks": [
{
"index": 123,
"reason": "malformed_url",
"value": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"instance": "<string>",
"invalid_tasks": [
{
"index": 123,
"reason": "malformed_url",
"value": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"instance": "<string>",
"invalid_tasks": [
{
"index": 123,
"reason": "malformed_url",
"value": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"instance": "<string>",
"invalid_tasks": [
{
"index": 123,
"reason": "malformed_url",
"value": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"instance": "<string>",
"invalid_tasks": [
{
"index": 123,
"reason": "malformed_url",
"value": "<string>"
}
]
}Authorizations
Headers
Optional opaque token scoping a single submit / rerun /
add-tasks request, kept for 24 hours. A retry with the same
key and the same body replays the original status and body.
The same key with a different body, or while the original
request is still being processed, returns
409 idempotency_key_conflict. A request that is refused
(any 4xx, or a 503 before the job or run was created)
gives the key back, so a retry with the same key is
processed afresh. A 503 after the job or run was created
keeps the key: a retry under it is 409; check the job
before you resend with a fresh key. On add-tasks a retry
with the same body finishes an attempt that stopped partway
and adds each task once. The credit check runs first, so a
retry of a call that succeeded returns 402 if the account
has run out of credit since. At most 128 characters; a
longer key is 400 invalid_argument.
128Body
regular: a run is created at submit time.scheduled: fires on a recurring or one-shot schedule. Submit stores the task list as a template on the job row; each scheduled fire produces a fresh Run.schedulefield required. Read-only template:addBatchTasksandclosereturn 409.rerun(full or filtered) andstopare allowed.
regular, scheduled Reference to a previously-uploaded CSV input (see
POST /v1/job_inputs). Mutually exclusive with tasks.
Eligible only for regular-closed and scheduled job types.
The uploaded CSV is parsed under the saved spec; its rows
become the tasks (regular-closed) or the task template
(scheduled).
Optional run.completed / run.failed delivery config.
A terminal run fires run.completed on a natural finish, or
run.failed (with failure_reason + partial stats) when the
run auto-fails on an account-level error. signature
defaults to false here so first-time integrations
don't need an HMAC key. Config is mutable post-submit
via PUT /v1/jobs/{id}/webhook and DELETE /v1/jobs/{id}/webhook; the current config is surfaced
on GET /v1/jobs/{id}.
Show child attributes
Show child attributes
Response
Job created (sync path). For a regular job, run 1 has started and all its task rows are written. A scheduled job has no run yet (latest_run is omitted) until its first fire.
open: initial run still acceptingaddBatchTasks. Only meaningful whilelatest_run.run_sequence == 1.closed: no more tasks accepted (created closed, or closed via/close/addTasks{last_batch}//rerun).deleted: never returned. A deleted job disappears from every read and list the momentDELETEis accepted (reads answer 404); its data is cleaned up asynchronously after.
Clients must accept values not listed here.
open, closed, deleted Was this page helpful?