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

Batch list

- 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 are selected.
    - `type` 'markdown' | 'html', required — Output format.
    - `tags` string[], required — Tags stored on the batch at submission.
    - `input` object, required — Submission counts.
      - `submitted` integer, required — Pages submitted before validation. For a crawl, the page limit.
      - `accepted` integer, required — Pages accepted, or the crawl page limit. Credits are reserved for this count.
      - `duplicates` integer, required — Duplicate URL and `itemId` pairs skipped. Always 0 for crawls.
      - `invalid` integer, required — Pages rejected during validation.
    - `progress` object, required — Current processing counts. Use `status` to check completion.
      - `succeeded` integer, required — Pages scraped successfully.
      - `failed` integer, required — Pages that could not be scraped.
      - `pending` integer, required — Accepted pages not yet attempted. Always 0 once the batch completes; a crawl can finish under its page limit when the site has no more reachable pages.
    - `credits` object, required — Reserved and used credits.
      - `estimated` integer, required — Credits reserved when the batch was accepted.
      - `charged` integer, required — Credits used by successful pages.
    - `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.
    - `errors` BatchErrorCount[], required — Page failures grouped by error code.
      - `code` string, required — Error code for these failures.
      - `count` integer, required — Pages that failed with this code.
    - `error` BatchNullableError, required — Why the batch failed.
      - `code` string, required — Batch error code.
      - `message` string, required — Batch error message.
    - `results` object, nullable, required — Download links available when the batch finishes. 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

## Changes

- **2026-07-31** `f5c503b03f98` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/context/apis/context-dev/changes/batch/list/get.md)

---

[API](https://skmtc.dev/context/apis/context-dev.md) · [All operations](https://skmtc.dev/context/apis/context-dev/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/context/context-dev/revisions/f5c503b03f98/schema)