---
title: "Cancel a batch"
method: POST
path: "/batch/{batch_id}/cancel"
tags: ["Batch"]
---

# Cancel a batch

`POST /batch/{batch_id}/cancel`

Stop a batch from starting new pages. In-progress pages finish, and unused credits are refunded.

## Path parameters

- `batch_id` string, required — ID of the batch to retrieve or cancel.

## Response `202`

Cancellation started. Poll `GET /batch/{batch_id}` until the batch settles.

- object — Acknowledgement that cancellation was requested. The batch has not settled, so it carries no results, no failure, no refund and no finish time; poll GET /batch/{batch_id} for those.
  - `id` string, required — Batch ID.
  - `status` 'cancelling', required — Always `cancelling`. Work already in flight finishes; the batch reaches `cancelled` shortly after.
  - `mode` 'scrape' | 'crawl', required — How pages were selected.
  - `format` 'markdown' | 'html', required — What each page is returned as.
  - `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 — How far the batch got before cancellation.
    - `succeeded` integer, required — Pages scraped successfully before the request landed.
    - `failed` integer, required — Pages that could not be scraped before the request landed.
    - `pending` integer, required — Reserved pages that will now be skipped, and refunded when the batch settles.
  - `credits` object, required — What this batch cost so far.
    - `reserved` integer, required — Credits debited at submission. The unspent remainder is refunded once the batch settles — read `credits.refunded` from GET /batch/{batch_id} then.
  - `timing` object, required — There is no finish time yet — the batch is still winding down.
    - `created_at` string, required — When the batch was created.
    - `started_at` string, nullable, required — When processing started. Null if it was cancelled while still queued.
  - `page_errors` BatchPageErrorCount[], required — Page failures so far, grouped by error code and sorted by count.
    - `code` string, required — Error code for these failures.
    - `count` integer, required — Pages that failed with this code.
  - `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
- `404` — Not found
- `409` — Batch already reached a terminal state, so there is nothing to cancel.

---

[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)