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 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.

Maximum string length: 128

Body

application/json
type
enum<string>
default:regular
  • 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. schedule field required. Read-only template: addBatchTasks and close return 409. rerun (full or filtered) and stop are allowed.
Available options:
regular,
scheduled
status
enum<string>
default:closed

Initial state. open is only allowed for regular jobs; after the initial run, open has no meaning so the job is auto-closed.

Available options:
open,
closed
zenrows_params
object

Job-level scraper params, applied to every task of every run of the job. Each task can override individual keys via its own zenrows_params (task wins on collision).

schedule
object

Schedule block for type: scheduled. Required there, ignored otherwise.

tasks
object[]

Required for closed jobs (1 to 100,000 tasks by default; an account can have its own limit) unless file_input_id is provided. Optional for open jobs: may be empty if the caller will follow up with addBatchTasks. Mutually exclusive with file_input_id.

file_input_id
string

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).

external_id
string

Optional caller-supplied correlation id for the job: same semantics as task.external_id. Shape-checked, not required to be unique. Surfaced verbatim in getBatchJob / listBatchJobs responses.

Maximum string length: 128
Pattern: ^[A-Za-z0-9._-]+$
name
string

Optional human-readable label for the job. Free-form: no shape rules. Up to 100 characters. Surfaced verbatim in getBatchJob / listBatchJobs responses. No uniqueness, no indexing; cannot be changed after submit.

Maximum string length: 100
metadata
object

Opaque user-supplied key/value pairs. Stored on the task; not forwarded.

webhook
object

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}.

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.

job_id
string
required
status
enum<string>
required
  • open: initial run still accepting addBatchTasks. Only meaningful while latest_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 moment DELETE is accepted (reads answer 404); its data is cleaned up asynchronously after.

Clients must accept values not listed here.

Available options:
open,
closed,
deleted
accepted_tasks
integer
required
latest_run
object

Absent for scheduled jobs that haven't fired yet.

webhook
object

Echo of the webhook config persisted on the job (when one was supplied). Omitted when no webhook was set.