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

# List runs of a job (newest first)



## OpenAPI

````yaml /api-reference/openapi.json get /jobs/{job_id}/runs
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}/runs:
    get:
      tags:
        - Batch
      summary: List runs of a job (newest first)
      operationId: listBatchRuns
      parameters:
        - $ref: '#/components/parameters/BatchJobID'
        - in: query
          name: limit
          description: >-
            Page size, 1 to 100 (larger values are treated as 100). Not a
            positive integer → 400.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - in: query
          name: cursor
          schema:
            type: string
      responses:
        '200':
          description: Page of runs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchListJobRunsResponse'
        '400':
          $ref: '#/components/responses/BatchInvalidArgument'
        '401':
          $ref: '#/components/responses/BatchUnauthenticated'
        '403':
          $ref: '#/components/responses/BatchForbidden'
        '404':
          $ref: '#/components/responses/BatchNotFound'
      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:
    BatchListJobRunsResponse:
      type: object
      required:
        - runs
      properties:
        runs:
          type: array
          items:
            $ref: '#/components/schemas/BatchRun'
        next_cursor:
          type: string
          description: Echo as `?cursor=` for the next page. Omitted on the last page.
    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.
    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
    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'
    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'
  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.