> ## 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.
# List Batches
> List your batches from newest to oldest. Filter by status or continue with a cursor.
0 Credits
## OpenAPI
````yaml GET /batch/list
openapi: 3.1.0
info:
title: Context API
description: API for retrieving context data from any website
version: 1.0.0
servers:
- url: https://api.context.dev/v1
security: []
tags:
- name: Batch
description: Scrape many pages or crawl a site asynchronously.
- name: Monitors
description: >-
Monitor pages, sitemaps, and extracted website data for exact or semantic
changes. Webhook payloads are documented by the
MonitorsChangeDetectedWebhookPayload and
MonitorsRunCompletedWebhookPayload schemas.
- name: WebDBs
description: Create structured tables from web pages and keep them up to date.
paths:
/batch/list:
get:
tags:
- Batch
summary: List batches
description: >-
List your batches from newest to oldest. Filter by status or continue
with a cursor.
operationId: listBatches
parameters:
- schema:
type: integer
minimum: 1
maximum: 100
description: Batches per page. Defaults to 25.
required: false
description: Batches per page. Defaults to 25.
name: limit
in: query
- schema:
type: string
description: Cursor from the previous page.
required: false
description: Cursor from the previous page.
name: cursor
in: query
- schema:
type: string
enum:
- queued
- running
- cancelling
- completed
- cancelled
- failed
description: Filter by status.
required: false
description: Filter by status.
name: status
in: query
- schema:
type: string
maxLength: 200
description: >-
Free-text search term, matched against the batch id, crawl source
(start URL or sitemap domain), and tags.
example: batch_1a2b
required: false
description: >-
Free-text search term, matched against the batch id, crawl source
(start URL or sitemap domain), and tags.
name: q
in: query
- schema:
type: string
enum:
- exact
- prefix
description: >-
`prefix` for as-you-type prefix matching (default), `exact` for
full-token matching.
required: false
description: >-
`prefix` for as-you-type prefix matching (default), `exact` for
full-token matching.
name: search_type
in: query
- schema:
type: string
description: >-
Comma-separated list of tags to filter by (matches batches having
any of them).
example: docs,competitor
required: false
description: >-
Comma-separated list of tags to filter by (matches batches having
any of them).
name: tags
in: query
responses:
'200':
description: >-
Your batches, newest first. Use `next_cursor` to page through the
rest.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Batch'
description: Batches on this page.
has_more:
type: boolean
description: Whether another page is available.
next_cursor:
type: string
nullable: true
description: Cursor for the next page.
key_metadata:
$ref: '#/components/schemas/KeyMetadata'
'401':
$ref: '#/components/responses/Unauthorized'
security:
- bearerAuth: []
x-codeSamples:
- lang: JavaScript
source: |-
import ContextDev from 'context.dev';
const client = new ContextDev({
apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted
});
const batches = await client.batch.list();
console.log(batches.data);
- lang: Python
source: |-
import os
from context.dev import ContextDev
client = ContextDev(
api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted
)
batches = client.batch.list()
print(batches.data)
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/context-dot-dev/context-go-sdk\"\n\t\"github.com/context-dot-dev/context-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tbatches, err := client.Batch.List(context.TODO(), contextdev.BatchListParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", batches.Data)\n}\n"
- lang: Ruby
source: |-
require "context_dev"
context_dev = ContextDev::Client.new(api_key: "My API Key")
batches = context_dev.batch.list
puts(batches)
- lang: PHP
source: >-
batch->list(
cursor: 'cursor',
limit: 1,
q: 'batch_1a2b',
searchType: 'exact',
status: 'queued',
tags: 'docs,competitor',
);
var_dump($batches);
} catch (APIException $e) {
echo $e->getMessage();
}
- lang: CLI
source: |-
context-dev batch list \
--api-key 'My API Key'
components:
headers:
RateLimitLimit:
description: >-
Maximum requests allowed in the current fixed one-minute window.
Returned when the authenticated API key has a per-minute rate limit.
schema:
type: integer
minimum: 1
RateLimitRemaining:
description: >-
Requests remaining in the current fixed one-minute window. Returned when
the authenticated API key has a per-minute rate limit.
schema:
type: integer
minimum: 0
RateLimitReset:
description: >-
Unix timestamp in seconds when the current rate-limit window resets.
Returned when the authenticated API key has a per-minute rate limit.
schema:
type: integer
schemas:
Batch:
type: object
properties:
id:
type: string
example: batch_9f2c8a
description: Batch ID used to retrieve or cancel the job.
status:
type: string
enum:
- queued
- running
- cancelling
- completed
- cancelled
- failed
description: Current state. `completed`, `cancelled`, and `failed` are final.
mode:
type: string
enum:
- scrape
- crawl
description: How pages were selected. Matches `input.mode` on the submit request.
format:
type: string
enum:
- markdown
- html
description: >-
What each page is returned as. Matches `input.data.format` on the
submit request.
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: 18091
description: Pages scraped successfully.
failed:
type: integer
example: 311
description: Pages that could not be scraped.
pending:
type: integer
example: 6415
description: >-
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.
required:
- succeeded
- failed
- pending
description: Pages attempted so far. Use `status` to check completion.
credits:
type: object
properties:
reserved:
type: integer
example: 24817
description: >-
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:
type: integer
example: 6726
description: >-
Credits returned for pages that did not succeed. Stays 0 until
the batch reaches a final status, then settles in one movement.
net:
type: integer
example: 18091
description: >-
`reserved` minus `refunded` — what the batch has cost so far.
Equal to `reserved` until the batch settles.
required:
- reserved
- refunded
- net
description: What this batch has done to your credit balance.
timing:
type: object
properties:
created_at:
type: string
description: When the batch was created.
started_at:
type:
- string
- 'null'
description: When processing started. Null while queued.
completed_at:
type:
- string
- 'null'
description: When processing finished. Null while active.
required:
- created_at
- started_at
- completed_at
page_errors:
type: array
items:
$ref: '#/components/schemas/BatchPageErrorCount'
description: >-
Individual page failures grouped by error code, sorted by count.
Unrelated to `failure`, which is the batch itself failing.
failure:
$ref: '#/components/schemas/BatchNullableFailure'
results:
type:
- object
- 'null'
properties:
expires_at:
type: string
description: When the download URLs expire.
files:
type: array
items:
type: object
properties:
url:
type: string
description: Temporary URL for a gzipped NDJSON file.
items:
type: integer
description: Results in this file.
bytes:
type: integer
description: Compressed file size in bytes.
required:
- url
- items
- bytes
description: Result files. Order is not guaranteed.
required:
- expires_at
- files
description: >-
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.
required:
- id
- status
- mode
- format
- tags
- crawl
- input
- progress
- credits
- timing
- page_errors
- failure
- results
title: Batch
description: An asynchronous web scraping job.
KeyMetadata:
type: object
properties:
credits_consumed:
type: integer
description: The number of credits consumed by this request.
credits_remaining:
type: integer
description: >-
The number of credits remaining for your organization after this
request.
required:
- credits_consumed
- credits_remaining
description: >-
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.
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 credits were reserved for. Everything else — progress, the
refund, the completion percentage — is measured against this.
reserved_is_ceiling:
type: boolean
example: false
description: >-
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:
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: >-
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.
required:
- reserved
- reserved_is_ceiling
- submitted
- duplicates
- invalid
x-stainless-model: batch.intake
description: What submission took in, and what it charged for.
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.
BatchNullableFailure:
anyOf:
- allOf:
- $ref: '#/components/schemas/BatchFailure'
- type: 'null'
description: >-
Why the batch as a whole stopped. Null unless `status` is `failed`.
Individual pages that failed are counted in `page_errors` instead.
ErrorResponse:
type: object
properties:
message:
type: string
description: 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
- WEBSITE_ACCESS_ERROR
- EXTERNAL_PROVIDER_ERROR
- INPUT_VALIDATION_ERROR
- ZDR_NOT_SUPPORTED
- ZDR_NOT_ENABLED
- FREE_EMAIL_DETECTED
- DISPOSABLE_EMAIL_DETECTED
- REQUEST_TIMEOUT
- UNSUPPORTED_CONTENT
- MONITOR_PAUSED
- MONITOR_NO_WEBHOOK
- COLLECTION_PAUSED
- MONITOR_LIMIT_EXCEEDED
- SEARCH_UNAVAILABLE
- BATCH_LIMIT_EXCEEDED
- BATCH_NOT_CANCELLABLE
- BATCH_NOT_COMPLETED
- IDEMPOTENCY_KEY_CONFLICT
description: Error code indicating the type of error
key_metadata:
$ref: '#/components/schemas/KeyMetadata'
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
- type: object
properties:
type:
type: string
enum:
- sitemap
domain:
type: string
example: example.com
description: Domain whose sitemap supplied the pages.
required:
- type
- domain
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: >-
The crawl controls as submitted, so the limits requested can be compared
against what the crawl reached.
BatchFailure:
type: object
properties:
code:
type: string
example: stalled
description: Why the batch itself stopped.
message:
type: string
example: Batch stopped reporting progress and was finalized automatically
description: Human-readable explanation.
required:
- code
- message
x-stainless-model: batch.failure
description: >-
A failure of the batch as a whole, distinct from the per-page failures
in `page_errors`.
responses:
Unauthorized:
description: Unauthorized
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Bearer authentication header of the form `Bearer `, where
`` is your api key.
````