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

# Start a new run (full replay or partial retry of the previous run)

> Two modes share this endpoint, picked by the optional
`?status=` filter:

**Full rerun (no `status`).** Replays every task from the
previous run into a fresh new run. Same `task_id` carries
through together with `external_id`, `url`, `metadata`, and
per-task `zenrows_params`. **No source-child link**: the
new run is fully independent. For scheduled jobs with no
prior run, builds from the job's task template instead: the
manual equivalent of an automatic scheduled fire.

**Partial retry (`?status=failed[,pending,...]`).** Copies
every prev-run task row, but rows matching the filter are
reset to `pending` and re-enqueued; everything else is
copied verbatim with `source_run_id` (the run that owns the
stored result) stamped. The new run's stats are pre-seeded
from the inherited terminal rows. On chained retries,
`source_run_id` chases back to the run that owns the result
so intermediate retries can be deleted freely;
`DELETE /v1/jobs/{id}/runs/{run_id}` only 409s when a
newer run still has tasks pointing at the targeted run.

Both modes stamp `trigger: manual` on the new run.

Accepted `status` values: `pending`, `processing`,
`failed`, `successful`. Unknown values → 400. `?status=`
with no value is the same as leaving it out (a full rerun); a
list with no values in it (`?status=,`) → 400.

Preconditions:
- The job is not `deleted`.
- If a previous run exists, it must be terminal-non-deleted
  (`completed` / `stopped` / `failed`), and its task ingestion
  must have finished: a run interrupted mid-ingest is refused
  with `409 run_not_terminal` (delete the job and resubmit).
- `?status=` mode additionally requires a prior run, created
  no more than 10 days ago; an older one is refused with
  `409 partial_rerun_window_expired` (a full rerun has no
  such limit).
- Full mode on a scheduled job with no prior run requires
  a non-empty task template.

Side effects:
- Auto-closes an `open` job (existing behavior).
- Honors `Idempotency-Key`: a repeat call with the same key
  and filter replays the original response (the same new
  run), also while that run is still in flight. A rerun
  refused before it started a run (`no_matching_tasks`,
  `no_prior_run`, a `503`) gives the key back, so the same
  key works once the cause is fixed.

Reruns are normally accepted asynchronously: the call returns
`202` and the new run's task rows stream into storage off the
request path. A deployment that processes reruns on the
request path answers `201` instead. Treat both as success.




## OpenAPI

````yaml /api-reference/openapi.json post /jobs/{job_id}/rerun
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}/rerun:
    post:
      tags:
        - Batch
      summary: Start a new run (full replay or partial retry of the previous run)
      description: |
        Two modes share this endpoint, picked by the optional
        `?status=` filter:

        **Full rerun (no `status`).** Replays every task from the
        previous run into a fresh new run. Same `task_id` carries
        through together with `external_id`, `url`, `metadata`, and
        per-task `zenrows_params`. **No source-child link**: the
        new run is fully independent. For scheduled jobs with no
        prior run, builds from the job's task template instead: the
        manual equivalent of an automatic scheduled fire.

        **Partial retry (`?status=failed[,pending,...]`).** Copies
        every prev-run task row, but rows matching the filter are
        reset to `pending` and re-enqueued; everything else is
        copied verbatim with `source_run_id` (the run that owns the
        stored result) stamped. The new run's stats are pre-seeded
        from the inherited terminal rows. On chained retries,
        `source_run_id` chases back to the run that owns the result
        so intermediate retries can be deleted freely;
        `DELETE /v1/jobs/{id}/runs/{run_id}` only 409s when a
        newer run still has tasks pointing at the targeted run.

        Both modes stamp `trigger: manual` on the new run.

        Accepted `status` values: `pending`, `processing`,
        `failed`, `successful`. Unknown values → 400. `?status=`
        with no value is the same as leaving it out (a full rerun); a
        list with no values in it (`?status=,`) → 400.

        Preconditions:
        - The job is not `deleted`.
        - If a previous run exists, it must be terminal-non-deleted
          (`completed` / `stopped` / `failed`), and its task ingestion
          must have finished: a run interrupted mid-ingest is refused
          with `409 run_not_terminal` (delete the job and resubmit).
        - `?status=` mode additionally requires a prior run, created
          no more than 10 days ago; an older one is refused with
          `409 partial_rerun_window_expired` (a full rerun has no
          such limit).
        - Full mode on a scheduled job with no prior run requires
          a non-empty task template.

        Side effects:
        - Auto-closes an `open` job (existing behavior).
        - Honors `Idempotency-Key`: a repeat call with the same key
          and filter replays the original response (the same new
          run), also while that run is still in flight. A rerun
          refused before it started a run (`no_matching_tasks`,
          `no_prior_run`, a `503`) gives the key back, so the same
          key works once the cause is fixed.

        Reruns are normally accepted asynchronously: the call returns
        `202` and the new run's task rows stream into storage off the
        request path. A deployment that processes reruns on the
        request path answers `201` instead. Treat both as success.
      operationId: rerunBatchJob
      parameters:
        - $ref: '#/components/parameters/BatchJobID'
        - in: query
          name: status
          description: |
            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`.
          schema:
            type: string
            example: failed,pending
        - $ref: '#/components/parameters/BatchIdempotencyKey'
      responses:
        '201':
          description: >-
            New run created synchronously; the API can answer this way instead
            of `202`. All task rows are written.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchRerunJobResponse'
        '202':
          description: |
            New run accepted. `retried_tasks` /
            `inherited_tasks` are the final counts, but individual
            task rows stream into storage off the request path.
            `latest_run.ingest_status` is `pending` in this response
            and flips to `done` on `GET /v1/jobs/{id}` once every
            task row is visible; the run's `stats.total` is correct
            from this response forward, so completion polling is
            safe. Body shape matches the 201 response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchRerunJobResponse'
        '400':
          $ref: '#/components/responses/BatchInvalidArgument'
        '401':
          $ref: '#/components/responses/BatchUnauthenticated'
        '402':
          $ref: '#/components/responses/BatchPaymentRequired'
        '403':
          $ref: '#/components/responses/BatchForbidden'
        '404':
          $ref: '#/components/responses/BatchNotFound'
        '409':
          description: |
            `run_not_terminal` (the latest run is in flight, or its
            ingestion was interrupted), `no_prior_run`,
            `no_matching_tasks`, `partial_rerun_window_expired`, or
            `idempotency_key_conflict` (the key was used with another
            filter, or that call is still in progress).
          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}$
    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:
    BatchRerunJobResponse:
      type: object
      required:
        - job_id
        - status
        - latest_run
        - retried_tasks
        - inherited_tasks
      properties:
        job_id:
          type: string
        status:
          $ref: '#/components/schemas/BatchJobStatus'
        latest_run:
          $ref: '#/components/schemas/BatchRun'
        rerun_of:
          type: string
          description: |
            `run_id` of the previous run that was replayed. Empty on
            the first manual fire of a scheduled job (no prior run).
        retried_tasks:
          type: integer
          description: |
            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:
          type: integer
          description: |
            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.
    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
    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.
    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).
    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'
    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'
    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.