Screenshot batches

Batches handle large URL lists through bounded, resumable submissions. Create a draft, upload chunks, then explicitly start processing. The dashboard's Batches page shows batches across your organization, including batches submitted through the API. Raw API keys can access only their own batches.

The default maximum is 100 items per batch. An administrator can increase your organization's limit, including above 10 million. Each new batch retains the limit from its creation; changing the organization setting does not change existing drafts. Large batches use the existing capture capacity, so increasing the size limit does not increase capture speed.

Create a draft

curl -X POST https://api.allscreenshots.com/v1/screenshots/batches \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Product catalog","defaults":{"format":"webp","fullPage":true}}'

The response contains the batch id, status: "DRAFT", maxBatchSize, and nextSequence: 0. Optional webhookUrl and webhookSecret configure a completion notification. Shared defaults accept the settings documented for bulk screenshots.

Append resumable chunks

curl -X POST https://api.allscreenshots.com/v1/screenshots/batches/BATCH_ID/chunks \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sequence":0,"entries":[
    {"url":"https://example.com/products/1","sourceLine":1},
    {"url":"https://example.com/products/2","sourceLine":2,"options":{"fullPage":false}}
  ]}'

Each chunk contains 1–1,000 entries and must fit within 8 MiB of JSON. Submit chunks sequentially, starting at zero. The receipt includes sequence, accepted (all stored entries), failed (invalid entries), and nextSequence.

Retry a chunk with the same sequence and identical request bytes after a timeout. It returns the existing receipt without duplicating items. Different bytes for an accepted sequence produce BATCH_CHUNK_CONFLICT; an out-of-order sequence produces BATCH_CHUNK_OUT_OF_ORDER. Read the summary's nextSequence to recover your submission position.

Duplicate URLs remain distinct captures. Invalid URLs or options are retained as failed items with an error and optional source line. Valid entries in the same chunk remain pending. A chunk exceeding the batch's size limit is rejected entirely with BATCH_LIMIT_EXCEEDED.

In the dashboard, upload TXT (one URL per line), CSV (a url column), or JSONL (url objects with optional options). Files are parsed incrementally in a worker. To resume after pausing or reloading, reselect the original file on the same browser. The importer reparses the file and skips accepted chunks; it does not hold the complete file or URL list in memory. Keep the file unchanged until submission finishes.

Chunk uploads use a separate organization-level ingestion allowance, defaulting to 100,000 requests/hour. Observe the X-RateLimit-* headers and Retry-After on HTTP 429. Starting a batch uses the organization's screenshot request allowance; monitoring requests use the general API allowance.

Start processing

POST /v1/screenshots/batches/{id}/start

A draft must contain at least one entry. Processing starts only after this call. In the dashboard, finish submission and review the item counts before choosing Start batch.

Captures reserve credits only while in flight. Successful captures consume credits; failed captures release their reservation. When credits run out, the batch enters WAITING_FOR_CREDITS and resumes automatically when credits become available. Processing survives application restarts, and stale workers cannot commit an item twice. A capture interrupted by a restart can be rendered again, but its committed result is charged once.

Monitor progress and individual items

GET /v1/screenshots/batches?limit=50&cursor=NEXT_CURSOR
GET /v1/screenshots/batches/{id}
GET /v1/screenshots/batches/{id}/items?limit=50&status=FAILED&cursor=NEXT_CURSOR

List responses contain items and nextCursor. Treat cursors as opaque strings. Page sizes are 1–100. Batch lists show newest first; items retain submission order. Item filters accept QUEUED, PROCESSING, COMPLETED, FAILED, or CANCELLED.

The summary provides totalJobs, completedJobs, failedJobs, processingJobs, pendingJobs, cancelledJobs, and progress (0–100). Items include their URL, status, sourceLine, errors, and result availability. Download available captures through job result endpoints.

Batch summaries also include createdAt, startedAt, and completedAt as UTC timestamps. startedAt records when the first capture is claimed. A new run has no start time while it is a draft, preparing, or waiting for its first capture (including waiting for credits). completedAt records when processing finishes, including cancellation after any in-flight captures settle. The dashboard shows Created, Started, and Finished in your local time, with seconds. Unavailable timestamps appear as a dash; older batches may not have a recorded start time.

Resuming preserves the batch's original startedAt and clears completedAt until it finishes again. Restarting creates a new batch with its own timestamps. A batch containing only invalid import entries can finish without ever starting a capture.

Statuses are DRAFT, PREPARING, QUEUED, PROCESSING, WAITING_FOR_CREDITS, COMPLETED, PARTIALLY_COMPLETED, FAILED, or CANCELLED. A cancelled batch can still have nonzero processingJobs while in-flight captures finish. PREPARING means that the worker is copying restart inputs or resetting cancelled items in bounded background steps. No captures begin until preparation finishes. For a restart, preparedJobs reports how many of totalJobs have been copied; item pages show the copied entries so far.

Resume a cancelled batch

POST /v1/screenshots/batches/{id}/resume

Choose Resume batch on the cancelled batch's dashboard page to continue its unfinished items. Completed results and failed items remain unchanged. Cancelled items, including individually cancelled items, become pending again. Successful new captures consume credits; previous captures are not repeated or charged again. A cancelled draft returns to DRAFT so you can finish uploading and explicitly start it.

Wait until processingJobs is zero before resuming. Repeating the request while the batch is preparing or active returns its current summary. If no unfinished items remain, restart instead. A batch waiting for credits still resumes automatically when credits become available.

Restart as a new run

curl -X POST https://api.allscreenshots.com/v1/screenshots/batches/BATCH_ID/restart \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"6be117a4-d3b3-4118-8d75-50318a3e8d3b"}'

Choose Restart batch to create a new run with the same URLs, duplicate entries, shared defaults, per-item settings, source lines, name, and webhook configuration. The original batch and its results stay available. All valid entries are captured again, including previous successes and capture failures. Entries with import errors remain failed because their original input has not changed. Successful captures in the new run consume credits.

The source must be finished or cancelled, with no captures in flight. The endpoint returns HTTP 202 with the new batch's summary and ID. Preparation is durable and paginated; it survives worker restarts without copying entries twice. Processing starts automatically after preparation finishes. The new run uses your organization's current batch-size limit, which must accommodate the complete source batch.

Generate a new UUID requestId for each intentional restart. Reuse that UUID when retrying the same request after a timeout: the API returns the existing new batch instead of creating another run. A UUID cannot be reused for a different source batch.

You can cancel a new run during preparation and resume it later from its checkpoint. Its source history is protected from deletion until copying finishes; to delete the source earlier, delete the cancelled new run first. Resuming and restarting use the screenshot request rate allowance, like starting a batch.

Cancel or delete

POST /v1/screenshots/batches/{id}/cancel
DELETE /v1/screenshots/batches/{id}

Cancellation immediately stops new capture claims. Pending items appear as cancelled without rewriting the entire batch. In-flight captures can finish and consume credits; completed results remain available.

Screenshot files follow the existing seven-day expiry. Batch and item history remain available after expiry or individual image deletion. To remove history, explicitly delete a finished or cancelled batch after its in-flight count reaches zero. Deletion returns HTTP 202 and removes items and remaining files in bounded background steps. Active batches must be cancelled first.

Completion webhooks

New batches send BATCH_COMPLETED with aggregate counts and an itemsUrl, rather than including every item in the payload. The notification remains queued until delivery succeeds and may be delivered more than once. Deduplicate using data.batchId or X-Webhook-Delivery-Id.

{
  "event": "BATCH_COMPLETED",
  "timestamp": "2026-10-09T10:00:00Z",
  "data": {
    "batchId": "BATCH_ID",
    "status": "PARTIALLY_COMPLETED",
    "totalJobs": 10000001,
    "completedJobs": 10000000,
    "failedJobs": 1,
    "cancelledJobs": 0,
    "itemsUrl": "https://api.allscreenshots.com/v1/screenshots/batches/BATCH_ID/items",
    "completedAt": "2026-10-09T10:00:00Z"
  }
}

Cancellation does not send a completion notification. See webhook signatures for verification.

Existing bulk API

POST /v1/screenshots/bulk retains its single-request maximum of 100 URLs and existing response and webhook shape. These jobs also appear in the dashboard's Batches list. Use the chunked batch API for larger submissions. Requests for a large batch through the legacy bulk detail endpoint return BATCH_REQUIRES_PAGINATION; use the batch item endpoint instead.

The legacy GET /v1/screenshots/jobs all-items list also returns BATCH_REQUIRES_PAGINATION when its caller has a batch larger than 100 items. This prevents loading a large batch into a single response. Individual job status and result endpoints remain available.