Skip to main content
POST
Create a batch job (many URLs in one request)

Authorizations

X-API-Key
string
header
required

Batch, Crawl, the Extract endpoints and the account endpoint read the same key from the X-API-Key header.

Headers

Idempotency-Key
string

Optional guard against creating duplicate jobs. Each key can be used once: the first submit with a key creates the job, and any later submit reusing it returns 409 idempotency_key_conflict, whether or not the body is identical. The original response is not replayed, so this is not a safe-retry token: if a submit fails midway, list your recent jobs to see whether it was created, then reuse its job_id or submit again with a new key.

Body

application/json
type
enum<string>
required

regular runs when submitted; scheduled runs on the schedule.

Available options:
regular,
scheduled
status
enum<string>
required

closed carries every URL now; open accepts URLs over time through addBatchTasks.

Available options:
closed,
open
name
string

Your own label for the job.

external_id
string

Your own identifier for the job.

metadata
object

Your own key-value data, returned with the job.

zenrows_params
object

Fetch parameters applied to every task, with the names the fetchPage operation uses.

tasks
object[]

The URLs to run, up to 100,000 per submit. Omit for an open job and when file_input_id is set.

Maximum array length: 100000
file_input_id
string

From uploadBatchInput, to run the job from an uploaded CSV instead of inline tasks. Always answers 202.

schedule
object

Exactly one of at, rate or calendar, plus timezone for at and calendar. Times of day are full hours; runs are at least 60 minutes apart.

webhook
object

Where run notifications (run.completed, run.failed) are delivered.

Response

Job accepted, under 10,000 inline tasks.

The answer to createBatchJob.

job_id
string
status
enum<string>
Available options:
open,
closed
accepted_tasks
integer
webhook
object

Where run notifications (run.completed, run.failed) are delivered.

latest_run
object

One run of a job.