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

# Page through per-task results for a specific run



## OpenAPI

````yaml /api-reference/openapi.json get /jobs/{job_id}/runs/{run_id}/results
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/{run_id}/results:
    get:
      tags:
        - Batch
      summary: Page through per-task results for a specific run
      operationId: getBatchRunResults
      parameters:
        - $ref: '#/components/parameters/BatchJobID'
        - $ref: '#/components/parameters/BatchRunID'
        - $ref: '#/components/parameters/BatchResultStatus'
        - $ref: '#/components/parameters/BatchResultCursor'
      responses:
        '200':
          description: Page of results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchListResultsResponse'
        '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}$
    BatchRunID:
      name: run_id
      in: path
      required: true
      description: Assigned by the server when a run is created (submit or rerun).
      schema:
        type: string
        pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
    BatchResultStatus:
      name: status
      in: query
      schema:
        type: string
        enum:
          - all
          - successful
          - failed
          - processing
        default: all
      description: |
        `processing` covers both `pending` and `processing` task
        states (anything not yet terminal).
    BatchResultCursor:
      name: cursor
      in: query
      schema:
        type: string
      description: Opaque pagination token; echo `next_cursor`.
  schemas:
    BatchListResultsResponse:
      type: object
      required:
        - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/BatchTaskResult'
        next_cursor:
          type: string
          description: Echo as `?cursor=` for the next page. Omitted on the last page.
    BatchTaskResult:
      type: object
      required:
        - task_id
        - run_id
        - url
        - status
        - created_at
        - updated_at
      properties:
        task_id:
          type: string
        external_id:
          type: string
          description: |
            Caller-supplied correlation id from submit/AddTasks.
            Omitted when the caller did not supply one.
        run_id:
          type: string
        url:
          type: string
          format: uri
        metadata:
          $ref: '#/components/schemas/BatchMetadata'
        method:
          type: string
          enum:
            - GET
            - POST
          description: |
            The task's HTTP method. Omitted for GET (the default).
            The request `body` is intentionally not part of listing
            responses.
        status:
          $ref: '#/components/schemas/BatchTaskStatus'
        type:
          $ref: '#/components/schemas/BatchResultType'
        result_url:
          type: string
          description: |
            Presigned download URL for the result body, valid for 2
            hours: fetch it soon after listing, and list again for a
            fresh one rather than storing it. Omitted for tasks that
            are not `successful`, including `expired` ones.
        error:
          $ref: '#/components/schemas/BatchProblem'
          description: |
            Present on failed tasks: the scraping engine's error as
            Problem JSON, or one of `gateway_unreachable` (503),
            `gateway_timeout` (504), `gateway_bad_response` or
            `internal` (500) when the attempt itself failed.
        source_run_id:
          type: string
          description: >
            Set when this row was copied from another run by

            `/rerun?status=`. The row keeps the status it had in the

            source run (usually terminal, but a `pending` row of a

            stopped run stays `pending`), is never re-executed, and its

            `result_url` resolves to the source run's stored result. On chained
            retries,

            `source_run_id` chases back to the run that actually

            owns the result. Empty for normally-executed rows.
        spend:
          $ref: '#/components/schemas/BatchTaskSpend'
          deprecated: true
          description: |
            Deprecated: the API does not send this field on result rows.
            Read per-task spend from the task's `/history` events (one
            `spend` per attempt) and the run total from `stats.spend`.
        created_at:
          type: string
          format: date-time
          description: When the task was created.
        updated_at:
          type: string
          format: date-time
          description: |
            The task's last update. Once a task is terminal
            (`successful` / `failed`) this is when it finished: use
            it to verify how fresh a result is on recurring jobs.
            On a row inherited by a partial rerun (`source_run_id`
            set) it is the time of the copy, not of the original
            scrape.
    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
    BatchMetadata:
      type: object
      description: Opaque user-supplied key/value pairs. Stored on the task; not forwarded.
      additionalProperties:
        type: string
        maxLength: 1024
      maxProperties: 20
    BatchTaskStatus:
      type: string
      x-extensible-enum: true
      enum:
        - pending
        - processing
        - successful
        - failed
        - expired
      description: |
        - `pending`, `processing`: not finished yet.
        - `successful`, `failed`: terminal.
        - `expired`: a successful task whose result body is past the
          job's result-visibility window (14 days by default). It has
          no `result_url`, and its `/content` returns
          `410 result_expired`. Result filters match the stored
          status, so `?status=successful` still returns these rows.

        Clients must accept values not listed here.
    BatchResultType:
      type: string
      x-extensible-enum: true
      enum:
        - html
        - json
        - markdown
        - plaintext
        - pdf
      description: |
        Body format of a successful task result: the task's effective
        format, derived (the same way as `BatchFormat`) from the job's
        `zenrows_params` merged with the task's own. A task that
        overrides `response_type` can differ from the job's `format`.

        Clients must accept values not listed here.
    BatchTaskSpend:
      type: object
      deprecated: true
      description: |
        Deprecated, kept so existing clients keep compiling: no response
        carries it. `total` summed every attempt and `last_attempt` the
        most recent one.
      required:
        - total
        - last_attempt
      properties:
        total:
          $ref: '#/components/schemas/BatchSpend'
        last_attempt:
          $ref: '#/components/schemas/BatchSpend'
    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.