---
title: "List batches"
method: GET
path: "/batch/list"
tags: ["Batch"]
---

# List batches

`GET /batch/list`

List your batches from newest to oldest. Filter by status or continue with a cursor.

## Query parameters

- `limit` integer — Batches per page. Defaults to 25.
- `cursor` string — Cursor from the previous page.
- `status` 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed' — Filter by status.
- `q` string — Free-text search term, matched against the batch id, crawl source (start URL or sitemap domain), and tags.
- `search_type` 'exact' | 'prefix' — `prefix` for as-you-type prefix matching (default), `exact` for full-token matching.
- `tags` string — Comma-separated list of tags to filter by (matches batches having any of them).

## Response `200`

Your batches, newest first. Use `next_cursor` to page through the rest.

- object
  - `data` Batch[] — Batches on this page.
    - `id` string, required — Batch ID used to retrieve or cancel the job.
    - `status` 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed', required — Current state. `completed`, `cancelled`, and `failed` are final.
    - `mode` 'scrape' | 'crawl', required — How pages were selected. Matches `input.mode` on the submit request.
    - `format` 'markdown' | 'html', required — What each page is returned as. Matches `input.data.format` on the submit request.
    - `tags` string[], required — Tags stored on the batch at submission.
    - `crawl` BatchNullableCrawlControls, required — The crawl controls as submitted, so the limits requested can be compared against what the crawl reached.
      - `source` union, required — Where the crawl started.
        - object — The crawl discovered pages by following links from one URL.
          - `type` 'start_url', required
          - `url` string, required — Page the crawl started from.
        - object — The crawl scraped the pages listed in the domain's sitemap.
          - `type` 'sitemap', required
          - `domain` string, required — Domain whose sitemap supplied the pages.
      - `max_pages` integer, required — The `maxUrls` submitted with the crawl. A sitemap crawl scrapes only the URLs its sitemap actually lists, up to this many, so `input.reserved` is often lower.
      - `max_depth` integer, nullable, required — Link depth limit. Always 0 for a sitemap crawl, which never follows links off its URLs; null when a `start_url` crawl set no limit.
      - `follow_subdomains` boolean, required — Whether links to subdomains were followed. Always false for a sitemap crawl.
      - `url_pattern` string, nullable, required — RE2 pattern URLs had to match to be crawled. Null when the crawl set none.
    - `input` BatchIntake, required — What submission took in, and what it charged for.
      - `reserved` integer, required — Pages credits were reserved for. Everything else — progress, the refund, the completion percentage — is measured against this.
      - `reserved_is_ceiling` boolean, required — Whether `reserved` is an upper bound the batch may finish under. True only for a crawl that follows links, whose reachable page count is unknowable until it runs. False for a scrape and for a sitemap crawl, where `reserved` is an exact page count.
      - `submitted` integer, nullable, required — URLs in the list you sent, before validation and de-duplication. Null for a crawl, which is given a source rather than a list.
      - `duplicates` integer, required — URLs dropped before reserving because another entry resolved to the same page. Non-zero for sitemap crawls too, whose sitemaps routinely list a page more than once.
      - `invalid` integer, nullable, required — URLs from your list rejected as unusable; the same ones are itemised in `invalid_urls` at submission. Null for a crawl — a crawl that resolves no usable page is rejected outright with a 400 rather than accepted with an empty list.
    - `progress` object, required — Pages attempted so far. Use `status` to check completion.
      - `succeeded` integer, required — Pages scraped successfully.
      - `failed` integer, required — Pages that could not be scraped.
      - `pending` integer, required — Reserved pages not yet attempted. A cancelled batch keeps reporting the URLs it never reached; a crawl whose `input.reserved_is_ceiling` is true reports 0 once final, because its unspent budget was never real pages.
    - `credits` object, required — What this batch has done to your credit balance.
      - `reserved` integer, required — Credits debited from your balance the moment the batch was accepted. This is a charge, not a forecast — the whole amount leaves the balance up front.
      - `refunded` integer, required — Credits returned for pages that did not succeed. Stays 0 until the batch reaches a final status, then settles in one movement.
      - `ocr_charged` integer, required — Credits charged for PDF pages recovered by OCR (pdf.ocr=true), 1 per recovered page, on top of `reserved`. Stays 0 until the batch settles.
      - `net` integer, required — `reserved` minus `refunded` plus `ocr_charged` — what the batch has cost so far. Equal to `reserved` until the batch settles.
    - `timing` object, required
      - `created_at` string, required — When the batch was created.
      - `started_at` string, nullable, required — When processing started. Null while queued.
      - `completed_at` string, nullable, required — When processing finished. Null while active.
    - `page_errors` BatchPageErrorCount[], required — Individual page failures grouped by error code, sorted by count. Unrelated to `failure`, which is the batch itself failing.
      - `code` string, required — Error code for these failures.
      - `count` integer, required — Pages that failed with this code.
    - `failure` BatchNullableFailure, required — A failure of the batch as a whole, distinct from the per-page failures in `page_errors`.
      - `code` string, required — Why the batch itself stopped.
      - `message` string, required — Human-readable explanation.
    - `results` object, nullable, required — Download links, available once the batch reaches a final status and null before then. GET /batch/{batch_id}/results serves the same records as paginated JSON.
      - `expires_at` string, required — When the download URLs expire.
      - `files` object[], required — Result files. Order is not guaranteed.
        - `url` string, required — Temporary URL for a gzipped NDJSON file.
        - `items` integer, required — Results in this file.
        - `bytes` integer, required — Compressed file size in bytes.
  - `has_more` boolean — Whether another page is available.
  - `next_cursor` string, nullable — Cursor for the next page.
  - `key_metadata` KeyMetadata — Metadata about the API key used for the request. Included in every response whenever a valid API key is provided, even when the response status is not 200.
    - `credits_consumed` integer, required — The number of credits consumed by this request.
    - `credits_remaining` integer, required — The number of credits remaining for your organization after this request.

## Other responses

- `401` — Unauthorized

---

[API](https://skmtc.net/context/apis/context-dev.md) · [All operations](https://skmtc.net/context/apis/context-dev/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/context/context-dev/versions/3c6a01ba967f/schema)