> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zenrows.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The Zenrows HTTP API serves Fetch and Extract (extract=auto) at https://api.zenrows.com/v1/, Crawl at https://api.zenrows.com/v1/crawls, and Batch at https://async.api.zenrows.com/v1. Fetch, Extract, Crawl and Batch are described in OpenAPI 3.1 at https://www.zenrows.com/openapi.json and listed in the RFC 9727 API catalog at https://www.zenrows.com/.well-known/api-catalog. Every endpoint also has its own page under /api-reference with its schema. Use the spec for exact parameter names and types. Crawl's endpoints, parameters and errors are also at https://docs.zenrows.com/crawl/endpoints.md. To call Zenrows from an agent, connect the MCP server at https://mcp.zenrows.com/mcp. To search these docs from an agent, connect the docs MCP server at https://docs.zenrows.com/mcp. Agent skills for Zenrows are published at https://github.com/ZenRows/cli and install with `npx skills add ZenRows/cli`.

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




## OpenAPI

````yaml /api-reference/openapi.json post /jobs
openapi: 3.1.0
info:
  title: Zenrows API
  version: 1.0.0
  summary: >-
    Reach any page, including the protected web, and return it as HTML,
    Markdown, plaintext, PDF or structured JSON.
  description: >-
    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 the `apikey` query
    parameter.

    - **Crawl**: collect the URLs behind one start page, at
    `https://api.zenrows.com/v1/crawls`. Authentication is the `X-API-Key`
    header or the `apikey` query parameter.

    - **Batch**: asynchronous jobs of up to 100,000 URLs, at
    `https://async.api.zenrows.com/v1`. Authentication is the `X-API-Key`
    header.


    **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.
  termsOfService: https://www.zenrows.com/legal/terms-of-use
  contact:
    name: Zenrows support
    email: support@zenrows.com
    url: https://www.zenrows.com/contact
  license:
    name: Proprietary
    url: https://www.zenrows.com/legal/terms-of-use
servers:
  - url: https://api.zenrows.com/v1
    description: Fetch and Extract (synchronous)
security:
  - apiKeyQuery: []
tags:
  - name: Fetch
    description: Retrieve one page, optionally rendered, proxied, converted or extracted.
  - name: Extract
    description: Which domains Extract serves, and getting a new one prepared.
  - name: Crawl
    description: Collect the URLs behind one start page, and each page's HTML when asked.
  - name: Batch
    description: Submit many URLs as one job and collect the results.
  - name: Account
    description: Plan, credits and concurrency for the calling key.
  - name: Onboarding
    description: Get a working key with no human in the loop.
externalDocs:
  description: Zenrows documentation
  url: https://docs.zenrows.com
paths:
  /jobs:
    post:
      tags:
        - Batch
      summary: Create a batch job (many URLs in one request)
      description: |
        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.
      operationId: createBatchJob
      parameters:
        - $ref: '#/components/parameters/BatchIdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchSubmitJobRequest'
      responses:
        '201':
          description: >-
            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.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchSubmitJobResponse'
        '202':
          description: |
            Job accepted (large submission). The validated task list
            is durable and `accepted_tasks` is the final count, but
            individual task rows stream into storage off the request
            path. `GET /v1/jobs/{id}/results` may return partial pages
            until ingest completes; the run's
            `stats.total` is correct from this response forward and
            `stats.completed` climbs from 0, so the run reaches
            `completed` only after every task drains: completion
            polling is safe. `latest_run.ingest_status` is `pending`
            in this response and flips to `done` on `GET /v1/jobs/{id}`
            once every task row is visible. Body shape matches the
            201 response.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchSubmitJobResponse'
        '400':
          $ref: '#/components/responses/BatchInvalidArgument'
        '401':
          $ref: '#/components/responses/BatchUnauthenticated'
        '402':
          $ref: '#/components/responses/BatchPaymentRequired'
        '403':
          $ref: '#/components/responses/BatchForbidden'
        '409':
          $ref: '#/components/responses/BatchIdempotencyConflict'
        '429':
          $ref: '#/components/responses/BatchQuotaExceeded'
        '503':
          $ref: '#/components/responses/BatchUnavailable'
      security:
        - apiKeyHeader: []
      servers:
        - url: https://async.api.zenrows.com/v1
          description: Batch (asynchronous jobs)
components:
  parameters:
    BatchIdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: |
        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`.
      schema:
        type: string
        maxLength: 128
  schemas:
    BatchSubmitJobRequest:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/BatchJobType'
        status:
          type: string
          enum:
            - open
            - closed
          default: closed
          description: |
            Initial state. `open` is only allowed for `regular` jobs;
            after the initial run, `open` has no meaning so the job
            is auto-closed.
        zenrows_params:
          $ref: '#/components/schemas/BatchScraperParams'
          description: |
            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:
          $ref: '#/components/schemas/BatchJobSchedule'
          description: |
            Schedule block for `type: scheduled`. Required there,
            ignored otherwise.
        tasks:
          type: array
          description: |
            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`.
          minItems: 0
          items:
            $ref: '#/components/schemas/BatchTaskInput'
        file_input_id:
          type: string
          description: |
            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:
          type: string
          maxLength: 128
          pattern: ^[A-Za-z0-9._-]+$
          description: |
            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.
        name:
          type: string
          maxLength: 100
          description: |
            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.
        metadata:
          $ref: '#/components/schemas/BatchMetadata'
        webhook:
          $ref: '#/components/schemas/BatchSubmitWebhookConfig'
          description: |
            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}`.
    BatchSubmitJobResponse:
      type: object
      required:
        - job_id
        - status
        - accepted_tasks
      properties:
        job_id:
          type: string
        status:
          $ref: '#/components/schemas/BatchJobStatus'
        latest_run:
          $ref: '#/components/schemas/BatchRun'
          description: Absent for `scheduled` jobs that haven't fired yet.
        accepted_tasks:
          type: integer
        webhook:
          $ref: '#/components/schemas/BatchWebhookConfig'
          description: |
            Echo of the webhook config persisted on the job (when
            one was supplied). Omitted when no webhook was set.
    BatchJobType:
      type: string
      enum:
        - regular
        - scheduled
      default: regular
      description: |
        - `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.
    BatchScraperParams:
      type: object
      description: |
        Subset of the Fetch parameters
        (https://docs.zenrows.com/fetch/api-reference).
        The API pins the surface to a known set: unknown keys are
        rejected with `400 invalid_argument` (`unknown_param`). The
        `screenshot*` family is deliberately excluded; `mode` accepts
        `"auto"` only for now.

        Each value can be any JSON scalar (string, boolean, integral
        number); the API stores it as a string.

        Per-task `zenrows_params` override job-level `zenrows_params`
        on key collision.

        Supported keys: `mode`, `js_render`, `js_instructions`,
        `custom_headers`, `premium_proxy`, `proxy_country`,
        `session_id`, `original_status`, `allowed_status_codes`,
        `wait_for`, `wait`, `block_resources`, `json_response`,
        `css_extractor`, `autoparse`, `extract`, `extract_fields`,
        `response_type`, `outputs`.

        `extract` selects the structured-extraction contract family
        (`auto`, `native`, or `standard`); `extract_fields` optionally
        narrows the returned fields. Extract works on any domain
        Zenrows has prepared, with any active API key; a task against a
        domain that isn't prepared yet fails with the scraper API's
        403 `REQS007`.

        `custom_headers` additionally accepts an object of header
        name → value pairs (or that object serialised as a JSON
        string), e.g. `{"custom_headers": {"Referer":
        "https://www.google.com/"}}`. The headers are forwarded to
        the scraping target, subject to the scraper API's usual
        header sanitisation. At most 32 headers / 8 KB serialised;
        names must be valid HTTP tokens. Header filtering and
        browser-header sanitisation follow the same rules as a
        single Fetch request.
        A task-level
        `custom_headers` replaces the job-level object wholesale:
        no per-name merging.
      additionalProperties:
        oneOf:
          - type: string
          - type: boolean
          - type: integer
          - type: object
            additionalProperties:
              type: string
    BatchJobSchedule:
      type: object
      description: |
        Structured scheduling block attached to `type: scheduled`
        jobs. Exactly one of `at`, `rate`, or `calendar` must be
        set.
      properties:
        at:
          type: string
          description: |
            One-shot fire at a specific wall-clock timestamp.
            Mutually exclusive with `rate` and `calendar`.

            **Must be tz-naive**: no trailing `Z`, no offset. The
            sibling `timezone` field (mandatory) is the single
            authoritative interpreter. This keeps DST transitions
            deterministic.
          example: '2026-09-01T09:00:00'
        rate:
          $ref: '#/components/schemas/BatchScheduleRate'
        calendar:
          $ref: '#/components/schemas/BatchScheduleCalendar'
        timezone:
          type: string
          description: |
            IANA timezone name (e.g. `Europe/Berlin`, `UTC`).
            **Required** when `at` or `calendar` is set;
            ignored by `rate` (interval-based, no wall-clock
            meaning). Anchoring wall-clock times to a named zone
            (rather than a UTC offset baked into the string) keeps
            DST transitions deterministic.
          example: Europe/Berlin
    BatchTaskInput:
      type: object
      required:
        - url
      properties:
        external_id:
          type: string
          maxLength: 128
          pattern: ^[A-Za-z0-9._-]+$
          description: |
            Optional caller-supplied correlation id: typically an
            identifier from the caller's own system. Surfaced verbatim
            in result/content responses so callers can match results
            back to their records. **Not required to be unique**:
            callers may reuse the same value across tasks (e.g. when
            multiple scrapes correlate to the same upstream record).
            Independent of the server-
            assigned `task_id`.
        url:
          type: string
          format: uri
          maxLength: 2048
          description: Must be http(s). Other schemes rejected at submit.
        metadata:
          $ref: '#/components/schemas/BatchMetadata'
        method:
          type: string
          enum:
            - GET
            - POST
          default: GET
          description: |
            HTTP method used against `url`. Case-insensitive. POST is
            for **safe/idempotent** requests only (GraphQL queries,
            search endpoints): tasks are retried on transient failures
            and reruns, so the target may see the same POST more than
            once. Don't send a request that must not run twice. POST
            rides the standard (non-headless)
            scraping path: combining it with `js_render`,
            `js_instructions`, or `json_response` is rejected with
            `400 invalid_argument`, the task's `invalid_tasks[].reason`
            being `method_param_conflict`.
        body:
          description: |
            Request body, only with `method: POST`. Any JSON value,
            16 KiB max. An object/array/number/boolean is sent as its
            JSON encoding with `Content-Type: application/json`; a
            string is sent verbatim with
            `Content-Type: application/x-www-form-urlencoded`. Set a
            different target Content-Type via the `custom_headers`
            zenrows param. Never echoed in results listings.
        zenrows_params:
          $ref: '#/components/schemas/BatchScraperParams'
          description: |
            Per-task scraper params. Override the job-level
            `zenrows_params` on key collision (task wins).
    BatchMetadata:
      type: object
      description: Opaque user-supplied key/value pairs. Stored on the task; not forwarded.
      additionalProperties:
        type: string
        maxLength: 1024
      maxProperties: 20
    BatchSubmitWebhookConfig:
      type: object
      required:
        - url
      description: |
        The webhook block accepted at submit: `url` is required and
        `signature` defaults to `false`. `PUT /v1/jobs/{id}/webhook`
        takes `BatchWebhookConfig`, which requires both.
      properties:
        url:
          type: string
          format: uri
          description: HTTPS URL that receives the run events.
        signature:
          type: boolean
          default: false
          description: >-
            Sign each delivery with the account's active HMAC key (see
            `BatchWebhookConfig.signature`).
    BatchJobStatus:
      type: string
      x-extensible-enum: true
      enum:
        - open
        - closed
        - deleted
      description: |
        - `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.
    BatchRun:
      type: object
      required:
        - run_id
        - job_id
        - run_sequence
        - status
        - stats
        - created_at
        - updated_at
      properties:
        run_id:
          type: string
        job_id:
          type: string
        run_sequence:
          type: integer
          minimum: 1
        status:
          $ref: '#/components/schemas/BatchRunStatus'
        trigger:
          $ref: '#/components/schemas/BatchRunTrigger'
        stats:
          $ref: '#/components/schemas/BatchRunStats'
        last_batch_received:
          type: boolean
          description: |
            Meaningful only for the initial run of an open job.
            Once true, `addBatchTasks` is rejected and the run drains
            into `completed`.
        pause_state:
          type: string
          enum:
            - active
            - paused
          description: |
            Reversible-suspend flag, orthogonal to `status`. A run
            never paused omits it; a resumed run returns `active`
            explicitly. Treat a missing field as `active`. Flip via
            `POST /jobs/{id}/pause` and `/resume`.
        ingest_status:
          type: string
          x-extensible-enum: true
          enum:
            - pending
            - done
          description: |
            Present only on runs created by a large (202) submission
            or a large (202) rerun. `pending`: task rows are still
            streaming into storage; reads may return partial pages
            and `addBatchTasks` returns `409`. `done`: every accepted
            task row is visible. Omitted on runs whose tasks were
            written on the request path (201 submissions and
            reruns, `addBatchTasks` batches).

            Clients must accept values not listed here.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        failure_reason:
          type: string
          x-extensible-enum: true
          enum:
            - insufficient_credits
            - subscription_inactive
            - api_key_cap_reached
          description: |
            Present only when `status == failed`: the account-level
            cause of the auto-fail. Omitted otherwise. Distinct from
            `stats.failure_reasons` (the per-task rollup).
            - `insufficient_credits`: the account is out of credits, or
              the plan doesn't include a feature the task needs.
            - `subscription_inactive`: the subscription is not active
              or has expired, the plan doesn't include the API, or the
              job's API key is no longer valid.
            - `api_key_cap_reached`: the job's API key reached one of
              its credit caps (day, week, month or billing period).
              Resolves on its own when that cap's window resets, or
              when the cap is raised.

            Clients must accept values not listed here.
        failure_detail:
          type: string
          description: |
            Human-readable explanation of `failure_reason`, e.g. which
            cap was reached and when it resets. Present only when
            `failure_reason` is. At most 500 characters (Unicode code
            points); longer upstream text is cut. Free text for display:
            branch on `failure_reason`, never on this string.
          example: Subscription has no credit available.
    BatchWebhookConfig:
      type: object
      required:
        - url
        - signature
      description: |
        Webhook delivery config for `run.completed` / `run.failed`. Returned on
        `GET /v1/jobs/{id}` (inline under `webhook`) and on
        `GET /v1/jobs/{id}/webhook`. `PUT` requires both fields:
        no defaulting at the mutate boundary (otherwise toggling
        `url` would silently disable signing). Submit body accepts
        the same shape with `signature` optional (defaults `false`).

        Delivery: one event per run that completes or fails on its own (a
        run stopped with `/stop` sends none), retried with backoff for up
        to 3 days, so the same event can arrive more than once; dedupe on
        `X-ZenRows-Event-Id`. Read `GET /v1/jobs/{id}` when you need to be
        sure a run finished.
      properties:
        url:
          type: string
          format: uri
          description: |
            HTTPS only. Host must resolve via DNS within 1 second
            (1+ A/AAAA record).
        signature:
          type: boolean
          description: |
            Opt-in HMAC signing. When `true`, each delivery is signed
            with the account's active HMAC key
            (`POST /v1/hmac/keys/rotate`) and carries
            `X-Signature: t=<unix>,v1=<hex>,kid=<active>`. The signed
            input is `t + "." + raw_body`, HMAC-SHA256, keyed with the
            secret's raw bytes: base64-decode the `secret` that
            `/rotate` returned before using it. When `false`,
            deliveries carry **no** `X-Signature` header: header
            absence is the signal.
    BatchProblem:
      type: object
      description: |
        RFC 7807 Problem Details.
      required:
        - type
        - title
        - status
        - code
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        code:
          type: string
          description: >
            Stable machine-readable error code. Branch on this, not on

            `detail` or `title`. `type` links to the code's entry in the

            public error reference. Codes and their usual status:


            | Status | Codes |

            |---|---|

            | 400 | `invalid_argument` (with `invalid_tasks` for per-task
            problems), `callback_url_must_be_https`,
            `callback_url_unresolvable`, `webhook_signing_requires_active_key` |

            | 401 | `unauthenticated`, `subscription_inactive` (a verified,
            enabled account whose subscription is past due, unpaid, incomplete
            or paused; `detail` stays "Subscription is not active.") |

            | 402 | `payment_required`, `api_key_cap_reached` |

            | 403 | `permission_denied` (the Batch API is not enabled for this
            account) |

            | 404 | `not_found` (job, run, task or export),
            `file_input_not_found` |

            | 409 | `conflict`, `job_not_open`, `last_batch_received`,
            `run_not_terminal`, `run_not_stoppable`, `no_prior_run`,
            `no_matching_tasks`, `run_has_descendants`,
            `idempotency_key_conflict`, `task_not_ready`,
            `partial_rerun_window_expired`, `candidate_pending`, `no_candidate`,
            `file_input_not_uploaded`, `file_input_unsupported_for_job_type` |

            | 410 | `result_expired` (a task's content past the result window,
            or an export past `expires_at`) |

            | 429 | `quota_exceeded` |

            | 500 / 503 | `internal` |


            A failed task's stored `error` uses the scraping engine's

            own codes, plus `gateway_unreachable` (503),

            `gateway_timeout` (504), `gateway_bad_response` and

            `internal` (500) for attempts that failed before the engine

            answered with Problem JSON.


            A path that matches no API route answers a plain `404`

            without a Problem body.


            Clients must accept values not listed here.
        instance:
          type: string
          description: Always `/v1`; it does not name the request path.
        invalid_tasks:
          type: array
          description: Present on validation errors.
          items:
            type: object
            required:
              - index
              - reason
            properties:
              index:
                type: integer
              reason:
                type: string
                x-extensible-enum: true
                description: Clients must accept values not listed here.
                enum:
                  - malformed_url
                  - unsupported_scheme
                  - missing_host
                  - url_too_long
                  - metadata_too_large
                  - metadata_key_invalid
                  - invalid_external_id
                  - unknown_param
                  - invalid_param_value
                  - unsupported_method
                  - body_not_allowed
                  - body_too_large
                  - body_malformed
                  - method_param_conflict
              value:
                type: string
                description: |
                  Offending input. For URL / metadata reasons this is
                  a redacted/truncated form of the bad value. For
                  `unknown_param` / `invalid_param_value` this is the
                  param key.
      additionalProperties: true
    BatchScheduleRate:
      type: object
      required:
        - every
        - unit
      description: |
        Interval-based fire policy: every N units. The interval must
        be at least 60 minutes by default (an account can have its own
        minimum); a shorter one returns `400 invalid_argument`.
      properties:
        every:
          type: integer
          minimum: 1
          example: 6
        unit:
          type: string
          enum:
            - minute
            - hour
            - day
          example: hour
    BatchScheduleCalendar:
      type: object
      required:
        - times_of_day
        - cadence
      description: |
        Calendar-style fire policy. Fires at every `times_of_day`
        entry on every day matching the cadence.
      properties:
        times_of_day:
          type: array
          minItems: 1
          description: |
            Wall-clock times on a 24-hour clock, full hours only
            (`"09:00"`, `"18:00"`). Minute granularity is rejected
            with 400.
          items:
            type: string
            pattern: ^([01][0-9]|2[0-3]):00$
          example:
            - '09:00'
            - '18:00'
        cadence:
          $ref: '#/components/schemas/BatchScheduleCadence'
    BatchRunStatus:
      type: string
      x-extensible-enum: true
      enum:
        - running
        - pending
        - completed
        - stopped
        - failed
        - deleted
      description: |
        In-flight:
        - `running`: work queued / in flight.
        - `pending`: initial run of an open job, idle between batches.

        Terminal:
        - `completed`: natural finish.
        - `stopped`: caller called `POST /jobs/{id}/stop`. No new
          tasks are picked up; in-flight tasks may still finish.
          Result bodies are kept. `stats.completed < stats.total`
          signals "stopped early".
        - `failed`: the run was auto-failed on an account-level error
          (insufficient credits / inactive subscription / the API key's
          credit cap reached). No new tasks are picked up;
          `failure_reason` and `failure_detail` carry the cause.
          Re-runnable once the account or cap is resolved. Result bodies already produced
          are kept.
        - `deleted`: caller called
          `DELETE /v1/jobs/{id}/runs/{run_id}`. The run's result
          bodies and data are being deleted; once complete the run
          disappears.

        Clients must accept values not listed here.
    BatchRunTrigger:
      type: string
      x-extensible-enum: true
      enum:
        - manual
        - scheduled
      description: |
        What set this run in motion. Always set.
        - `manual`: caller-initiated: `POST /jobs`, `POST /jobs/{id}/rerun`
          (any job type, full or `?status=`-filtered, manual fire of
          a scheduled job).
        - `scheduled`: automatic, fired by the configured
          schedule (recurring or one-shot).

        Clients must accept values not listed here.
    BatchRunStats:
      type: object
      required:
        - total
        - completed
        - successful
        - failed
      properties:
        total:
          type: integer
          description: Number of tasks in this run.
        completed:
          type: integer
          description: successful + failed.
        successful:
          type: integer
        failed:
          type: integer
        failure_reasons:
          type: object
          description: |
            Coarse rollup of terminal failures keyed by a small public
            taxonomy. Lets you answer "what kinds of failures did I
            get?" without paging every error blob. Best-effort,
            indicative: omitted on runs with no failures yet and on
            runs that predate the feature.

            Vocabulary (the only keys that appear):
            - `auth_failed`: credentials or billing
            - `blocked`: anti-bot / policy denials, including a bot wall
              Extract met on the fetched page
            - `bad_target`: target URL is the problem (bad host, 404, 410,
              too large, or a page Extract does not cover or found no data on)
            - `rate_limited`: target throttled the request
            - `timeout`: the scrape didn't complete in time
            - `gateway_error`: Zenrows-side transport / 5xx
            - `other`: anything else
          additionalProperties:
            type: integer
            minimum: 0
          example:
            blocked: 9
            gateway_error: 4
        spend:
          allOf:
            - $ref: '#/components/schemas/BatchSpend'
          description: |
            Indicative spend summed across every task attempt in
            this run. Absent on runs whose tasks predate this
            field (treat as zero).
    BatchScheduleCadence:
      type: object
      description: |
        Picks which days the schedule fires on. Exactly one of
        `daily`, `weekly`, `monthly` must be set.
      properties:
        daily:
          type: object
          description: Fire every day. No knobs.
        weekly:
          type: object
          required:
            - days
          properties:
            days:
              type: array
              minItems: 1
              items:
                type: string
                enum:
                  - mon
                  - tue
                  - wed
                  - thu
                  - fri
                  - sat
                  - sun
              example:
                - mon
                - wed
                - fri
        monthly:
          type: object
          required:
            - days
          properties:
            days:
              type: array
              minItems: 1
              items:
                type: integer
                minimum: 1
                maximum: 31
              example:
                - 1
                - 15
    BatchSpend:
      type: object
      description: |
        Indicative `{credits, cost}` pair: what was charged for
        the scoped work. **Not billing-grade**; your account
        statement is authoritative. Use as a "how much did this
        cost?" indicator, not for reconciliation.
      required:
        - credits
        - cost
      properties:
        credits:
          type: integer
          minimum: 0
        cost:
          type: number
          format: double
          minimum: 0
  headers:
    XRequestId:
      description: Identifier for this request. Quote it when reporting a problem.
      schema:
        type: string
        example: 67fa4e35647515d8ad61bb3ee041e1bb
  responses:
    BatchInvalidArgument:
      description: Request validation failed.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BatchProblem'
    BatchUnauthenticated:
      description: Missing / invalid API key.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BatchProblem'
    BatchPaymentRequired:
      description: |
        The run cannot start because of billing. The problem `code`
        tells the cases apart:
        - `payment_required`: the subscription has expired, has no
          credit available, or its plan does not include the API
          ("Subscription does not allow access to this service.").
        - `api_key_cap_reached`: this API key reached one of its
          credit caps. `detail` names the window, the cap and when it
          resets (UTC). Other keys on the account are unaffected.

        Clients must accept `code` values not listed here.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BatchProblem'
    BatchForbidden:
      description: |
        `permission_denied`: the Batch API is not enabled for this
        account. Any `/v1` route can return it.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BatchProblem'
    BatchIdempotencyConflict:
      description: |
        `idempotency_key_conflict`: the Idempotency-Key was already
        used by this caller with a different body, or the first
        request with it is still in progress (or answered `503` after
        it created the job).
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BatchProblem'
    BatchQuotaExceeded:
      description: >
        `quota_exceeded`: an account cap is reached. On submit: the

        account already has its maximum of active regular jobs (3 by

        default, Crawl jobs included; an open job counts until it is closed) or
        of

        scheduled jobs (5 by default). On add-tasks: the open job's

        run would go over 100,000 tasks. For a job cap, finish, close

        or delete a job, then retry; for the task cap, send fewer

        tasks or close the job. A refused submit gives its

        `Idempotency-Key` back, so the retry can reuse it; an

        add-tasks retry with the same body is checked again. No

        `Retry-After` is sent: the cap clears when a job finishes or

        is deleted, not with time.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BatchProblem'
    BatchUnavailable:
      description: Transient upstream failure; safe to retry.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BatchProblem'
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: apikey
      description: >-
        Fetch, Extract, Crawl and the account endpoint accept the key as the
        `apikey` query parameter. Keys are per account and self-serve: create
        one in the Zenrows dashboard (app.zenrows.com), or, for an agent with no
        human present, `POST https://app.zenrows.com/api/agent/signup`.
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Batch, Crawl, the Extract endpoints and the account endpoint read the
        same key from the `X-API-Key` header.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.