Skip to main content
POST
Start a new run (full replay or partial retry of the previous run)

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

Path Parameters

job_id
string
required

Assigned by the server on submit.

Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$

Query Parameters

status
string

Optional comma-separated list of task statuses to retry. When omitted: full replay (no source-child link). When set: only matching statuses are reset to pending; everything else is inherited with source_run_id.

Example:

"failed,pending"

Response

New run created synchronously; the API can answer this way instead of 202. All task rows are written.

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
latest_run
object
required
retried_tasks
integer
required

Number of rows reset to pending and re-enqueued. Equals latest_run.stats.total for a full rerun; equals the filter-matched count for a ?status= partial retry.

inherited_tasks
integer
required

Number of rows copied verbatim from the previous run with source_run_id stamped. Zero for a full rerun; non-zero only when ?status= is set.

rerun_of
string

run_id of the previous run that was replayed. Empty on the first manual fire of a scheduled job (no prior run).