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

# Pause or resume a scheduled job

> Flips `schedule_state` between `active` and `paused`. Only
valid on `type: scheduled` jobs.

While `paused`, scheduled fires are skipped; resuming makes
the next scheduled fire produce a run normally.

`next_scheduled_run` is omitted while paused: no fire is
coming until you resume.




## OpenAPI

````yaml /api-reference/openapi.json post /jobs/{job_id}/schedule/state
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/{job_id}/schedule/state:
    post:
      tags:
        - Batch
      summary: Pause or resume a scheduled job
      description: |
        Flips `schedule_state` between `active` and `paused`. Only
        valid on `type: scheduled` jobs.

        While `paused`, scheduled fires are skipped; resuming makes
        the next scheduled fire produce a run normally.

        `next_scheduled_run` is omitted while paused: no fire is
        coming until you resume.
      operationId: setBatchScheduleState
      parameters:
        - $ref: '#/components/parameters/BatchJobID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchUpdateScheduleStateRequest'
      responses:
        '200':
          description: Schedule state updated; returns the updated Job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchJob'
        '400':
          $ref: '#/components/responses/BatchInvalidArgument'
        '401':
          $ref: '#/components/responses/BatchUnauthenticated'
        '403':
          $ref: '#/components/responses/BatchForbidden'
        '404':
          $ref: '#/components/responses/BatchNotFound'
        '409':
          description: Job isn't a scheduled job.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BatchProblem'
        '503':
          $ref: '#/components/responses/BatchUnavailable'
      security:
        - apiKeyHeader: []
      servers:
        - url: https://async.api.zenrows.com/v1
          description: Batch (asynchronous jobs)
components:
  parameters:
    BatchJobID:
      name: job_id
      in: path
      required: true
      description: Assigned by the server on submit.
      schema:
        type: string
        pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
  schemas:
    BatchUpdateScheduleStateRequest:
      type: object
      required:
        - schedule_state
      properties:
        schedule_state:
          $ref: '#/components/schemas/BatchScheduleState'
    BatchJob:
      type: object
      required:
        - job_id
        - type
        - status
        - created_at
        - updated_at
      properties:
        job_id:
          type: string
        type:
          $ref: '#/components/schemas/BatchJobType'
        status:
          $ref: '#/components/schemas/BatchJobStatus'
        format:
          $ref: '#/components/schemas/BatchFormat'
        template_tasks:
          type: array
          description: |
            A scheduled job's task template, when it is small enough to
            be stored inline on the job; omitted otherwise (a large
            template is stored separately and not returned here).
          items:
            $ref: '#/components/schemas/BatchTaskInput'
        zenrows_params:
          type: object
          additionalProperties:
            type: string
          description: |
            Stored canonical form: values are always strings even
            though submit accepts any JSON scalar (see ScraperParams).
        external_id:
          type: string
          description: |
            Caller-supplied correlation id passed at submit (omitted
            when the caller did not supply one). Not server-enforced
            unique.
        name:
          type: string
          description: |
            Optional human label passed at submit (omitted when the
            caller did not supply one). Free-form, up to 100 chars.
        metadata:
          $ref: '#/components/schemas/BatchMetadata'
        schedule:
          $ref: '#/components/schemas/BatchJobSchedule'
          description: |
            Schedule block: present only for `type: scheduled`
            jobs.
        next_scheduled_run:
          type: string
          format: date-time
          description: |
            The next expected fire, computed from the schedule when
            the response is built. Omitted for non-scheduled jobs,
            while `schedule_state == paused`, and for a one-shot `at`
            schedule that has already fired.
        schedule_state:
          $ref: '#/components/schemas/BatchScheduleState'
          description: |
            Set only for `type: scheduled`. Default `active` at
            submit; flip via `POST /v1/jobs/{id}/schedule/state`.
        webhook:
          $ref: '#/components/schemas/BatchWebhookConfig'
          description: |
            Webhook delivery config. Present iff a
            webhook is configured. Mutable via `PUT/DELETE
            /v1/jobs/{id}/webhook`; `signature` never appears
            alone: the whole `webhook` key is omitted when no
            URL is set.
        latest_run:
          $ref: '#/components/schemas/BatchRun'
          description: |
            The job's most recent run, read when the response is
            built. Absent for `scheduled` jobs that haven't fired yet,
            and once every run was deleted.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    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
    BatchScheduleState:
      type: string
      enum:
        - active
        - paused
      description: |
        Run/pause flag on a scheduled job. While `paused`, scheduled
        fires are skipped. Default at submit: `active`. Flip via
        `POST /v1/jobs/{id}/schedule/state`.
    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.
    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.
    BatchFormat:
      type: string
      x-extensible-enum: true
      enum:
        - html
        - json
        - markdown
        - plaintext
        - pdf
      description: |
        Derived server-side from `zenrows_params` at submit time.
        Precedence:
          - `response_type: markdown|plaintext|pdf` → matching format.
          - a non-empty `include` → `json`, ahead of `response_type`.
          - `autoparse: true`, `json_response: true`, or non-empty
            `css_extractor` or `extract` → `json`. (`outputs` returns
            JSON from the scraper but is not part of this derivation, so
            such a result is typed `html`; kept as is for existing
            clients.)
          - otherwise → `html`.
        The job's `format` is the default from its job-level params;
        each task result's `type` is derived from that task's merged
        params and sets the `Content-Type` of its content.

        Clients must accept values not listed here.
    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
    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
    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.
    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.
    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
    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
  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'
    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'
    BatchNotFound:
      description: Resource not found (or not owned by caller).
      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.