> ## Documentation Index
> Fetch the complete documentation index at: https://docs.context.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Setting up Context.dev for a user? Follow https://docs.context.dev/agent-quickstart.md. Start by signing the user up and getting an API key through https://www.context.dev/auth.md; application code reads CONTEXT_DEV_API_KEY.
# Cancel a batch
> Stop a batch from starting new pages. Pages already in progress finish before the batch becomes cancelled.
0 credits
Requires [`batches:write` permission](/account/api-keys). See the [guide](/batches/limits-and-errors) for examples and usage.
## OpenAPI
````yaml POST /batch/{batch_id}/cancel
openapi: 3.1.0
info:
title: Context.dev API
description: >-
Scrape, crawl, search, and monitor websites, and retrieve brand, people, and
news data.
version: 1.0.0
servers:
- url: https://api.context.dev/v1
security: []
tags:
- name: Webhooks
description: Inspect and retry batch and monitor webhook deliveries.
- name: Logs
description: Read your organization's API request logs.
- name: Usage
description: Read your organization's credit balance and usage history.
- name: Agent Feedback
description: Report API issues and documentation mismatches.
- name: Batches
description: Scrape many pages or crawl a site asynchronously.
- name: Monitors
description: Watch websites for exact or meaningful changes.
- name: News
description: Search live and historical news about a company.
- name: Answers
description: Answer a research task from the live web in the JSON shape you ask for.
paths:
/batch/{batch_id}/cancel:
post:
tags:
- Batches
summary: Cancel a batch
description: >-
Stop a batch from starting new pages. Pages already in progress finish
before the batch becomes cancelled.
operationId: cancelBatch
parameters:
- schema:
type: string
example: batch_9f2c8a
description: Batch ID.
required: true
description: Batch ID.
name: batch_id
in: path
responses:
'202':
description: >-
Cancellation started. Poll `GET /batch/{batch_id}` until the batch
settles.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
X-RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-RateLimit-Mode:
$ref: '#/components/headers/RateLimitMode'
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BatchCancelling'
- type: object
properties:
key_metadata:
$ref: '#/components/schemas/KeyMetadata'
description: API key usage for this request.
request_id:
$ref: '#/components/schemas/RequestId'
required:
- request_id
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: >-
API key permissions or organization settings do not allow this
request.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
X-RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-RateLimit-Mode:
$ref: '#/components/headers/RateLimitMode'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
$ref: '#/components/responses/NotFound'
'409':
description: Batch already finished (`BATCH_NOT_CANCELLABLE`).
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
X-RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-RateLimit-Mode:
$ref: '#/components/headers/RateLimitMode'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
$ref: '#/components/responses/RateLimited'
security:
- bearerAuth: []
components:
headers:
RequestId:
description: Unique ID of this request; also `request_id` in JSON bodies.
schema:
type: string
format: uuid
RateLimitLimit:
description: >-
Maximum request units per minute, or maximum concurrent requests when
X-RateLimit-Mode is concurrency.
schema:
type: integer
minimum: 1
RateLimitRemaining:
description: >-
Request units remaining in the current minute, or concurrent requests
still available when X-RateLimit-Mode is concurrency.
schema:
type: integer
minimum: 0
RateLimitReset:
description: >-
Unix timestamp in seconds when the per-minute rate limit resets. Omitted
for concurrency limits.
schema:
type: integer
RateLimitMode:
description: >-
Set to concurrency when the organization is limited by concurrent
requests. Omitted for per-minute limits.
schema:
type: string
enum:
- concurrency
schemas:
BatchCancelling:
type: object
properties:
id:
type: string
example: batch_9f2c8a
description: Batch ID.
status:
type: string
enum:
- cancelling
description: >-
Always `cancelling`. Work already in flight finishes; the batch
reaches `cancelled` shortly after.
mode:
type: string
enum:
- scrape
- crawl
description: How pages were selected.
format:
type: string
enum:
- markdown
- html
description: What each page is returned as.
tags:
type: array
items:
type: string
description: Tags stored on the batch at submission.
example:
- docs
crawl:
$ref: '#/components/schemas/BatchNullableCrawlControls'
input:
$ref: '#/components/schemas/BatchIntake'
progress:
type: object
properties:
succeeded:
type: integer
example: 4120
description: Pages scraped successfully before the request landed.
failed:
type: integer
example: 37
description: Pages that could not be scraped before the request landed.
pending:
type: integer
example: 20660
description: Pages that will be skipped.
required:
- succeeded
- failed
- pending
description: How far the batch got before cancellation.
credits:
type: object
properties:
reserved:
type: integer
example: 24817
description: >-
Credits held at submission; unused credits are refunded when the
batch settles.
required:
- reserved
description: What this batch cost so far.
timing:
type: object
properties:
created_at:
type: string
description: When the batch was created.
started_at:
type:
- string
- 'null'
description: >-
When processing started. Null if it was cancelled while still
queued.
required:
- created_at
- started_at
description: Batch timestamps.
page_errors:
type: array
items:
$ref: '#/components/schemas/BatchPageErrorCount'
description: Page failures so far, grouped by error code and sorted by count.
required:
- id
- status
- mode
- format
- tags
- crawl
- input
- progress
- credits
- timing
- page_errors
title: Cancelling batch
description: >-
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.
KeyMetadata:
type: object
properties:
credits_consumed:
type: integer
description: Credits charged for this request.
credits_remaining:
type: integer
description: Credits remaining for your organization.
required:
- credits_consumed
- credits_remaining
description: Credits this request used and your remaining balance.
RequestId:
type: string
format: uuid
description: >-
Unique ID of this request, also in `X-Request-Id`. Include it when
contacting support.
example: 3f1c2a6e-8b4d-4c1e-9f0a-2d7b5e6c8a91
ErrorResponse:
type: object
properties:
message:
type: string
description: Human-readable error message.
error_code:
type: string
enum:
- INTERNAL_ERROR
- VALID
- NOT_FOUND
- FORBIDDEN
- USAGE_EXCEEDED
- RATE_LIMITED
- UNAUTHORIZED
- DISABLED
- PAID_PLAN_REQUIRED
- INSUFFICIENT_PERMISSIONS
- TIMEOUT_EXCEEDS_MAXIMUM
- TIMEOUT_TOO_SHORT_FOR_WAIT
- WEBSITE_ACCESS_ERROR
- WEBSITE_BLOCKED
- WEBSITE_NOT_FOUND
- PDF_SKIPPED
- PDF_IMAGES_ONLY
- INPUT_VALIDATION_ERROR
- ZDR_NOT_SUPPORTED
- ZDR_NOT_ENABLED
- FREE_EMAIL_DETECTED
- DISPOSABLE_EMAIL_DETECTED
- REQUEST_TIMEOUT
- COLD_DOMAIN_TIMEOUT_TOO_LOW
- UNSUPPORTED_CONTENT
- CONTENT_TOO_LARGE
- MONITOR_PAUSED
- MONITOR_NO_WEBHOOK
- COLLECTION_PAUSED
- MONITOR_LIMIT_EXCEEDED
- SEARCH_UNAVAILABLE
- BATCH_LIMIT_EXCEEDED
- BATCH_NOT_CANCELLABLE
- BATCH_NOT_COMPLETED
- IDEMPOTENCY_KEY_CONFLICT
- DELIVERY_IN_PROGRESS
- DELIVERY_ALREADY_DELIVERED
- DELIVERY_EXPIRED
- DELIVERY_CANCELLED
description: Machine-readable error code.
required_permission:
type: string
enum:
- logs:read
- data:execute
- monitors:read
- monitors:write
- batches:read
- batches:write
description: >-
Permission required for this request when error_code is
INSUFFICIENT_PERMISSIONS. Manage (write) also grants read access to
the same resource group.
key_metadata:
$ref: '#/components/schemas/KeyMetadata'
request_id:
$ref: '#/components/schemas/RequestId'
required:
- request_id
BatchNullableCrawlControls:
anyOf:
- allOf:
- $ref: '#/components/schemas/BatchCrawlControls'
- type: 'null'
description: How the crawl was configured. Null for scrape batches.
BatchIntake:
type: object
properties:
reserved:
type: integer
example: 24817
description: Pages accepted; progress counts toward this total.
reserved_is_ceiling:
type: boolean
example: false
description: >-
True when `reserved` is a crawl ceiling; false when it is an exact
URL count.
submitted:
type:
- integer
- 'null'
example: 25000
description: >-
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:
type: integer
example: 183
description: >-
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:
type:
- integer
- 'null'
example: 0
description: Rejected input URLs; `null` for a crawl.
required:
- reserved
- reserved_is_ceiling
- submitted
- duplicates
- invalid
x-stainless-model: batch.intake
description: What the submission accepted.
BatchPageErrorCount:
type: object
properties:
code:
type: string
example: WEBSITE_ACCESS_ERROR
description: Error code for these failures.
count:
type: integer
example: 204
description: Pages that failed with this code.
required:
- code
- count
x-stainless-model: batch.page_error_count
description: Page failures sharing one error code.
BatchCrawlControls:
type: object
properties:
source:
anyOf:
- type: object
properties:
type:
type: string
enum:
- start_url
url:
type: string
example: https://example.com/docs
description: Page the crawl started from.
required:
- type
- url
title: Start URL
description: The crawl discovered pages by following links from one URL.
- type: object
properties:
type:
type: string
enum:
- sitemap
domain:
type: string
example: example.com
description: Domain whose sitemap supplied the pages.
required:
- type
- domain
title: Sitemap
description: The crawl scraped the pages listed in the domain's sitemap.
description: Where the crawl started.
max_pages:
type: integer
example: 500
description: >-
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:
type:
- integer
- 'null'
example: 0
description: >-
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:
type: boolean
description: >-
Whether links to subdomains were followed. Always false for a
sitemap crawl.
url_pattern:
type:
- string
- 'null'
example: ^https://example\.com/docs/
description: >-
RE2 pattern URLs had to match to be crawled. Null when the crawl set
none.
required:
- source
- max_pages
- max_depth
- follow_subdomains
- url_pattern
x-stainless-model: batch.crawl_controls
title: Crawl controls
description: Crawl settings as submitted.
responses:
BadRequest:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
X-RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-RateLimit-Mode:
$ref: '#/components/headers/RateLimitMode'
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
X-RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-RateLimit-Mode:
$ref: '#/components/headers/RateLimitMode'
NotFound:
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
X-RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-RateLimit-Mode:
$ref: '#/components/headers/RateLimitMode'
RateLimited:
description: Rate limit exceeded
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
X-RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-RateLimit-Mode:
$ref: '#/components/headers/RateLimitMode'
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
minimum: 1
maximum: 60
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Human-readable error message.
error_code:
type: string
enum:
- RATE_LIMITED
description: Error code indicating the rate limit was exceeded
key_metadata:
$ref: '#/components/schemas/KeyMetadata'
request_id:
$ref: '#/components/schemas/RequestId'
required:
- request_id
- message
- error_code
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Send `Authorization: Bearer `. Keys have full access unless
restricted to scopes.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.