API ReferenceBulk

Get bulk job status

Returns the job envelope. Items are listed by GET /v1/bulk/{id}/screenshots.

Cancelled by the platform. When the account can no longer spend (its bandwidth balance is exhausted, or the account is deleted) while items are still pending, ByteKit cancels the job itself. It then reads status: cancelled even though you never called DELETE /v1/bulk/{id}, and the cancellation sends no webhook.

Job ids from other create routes. The job is looked up by account only, so the id of a job created by POST /v1/scrape/bulk or POST /v1/fetch/bulk is found here too, not a 404, with that job's envelope. An id from another account answers 404.

For AI agents: https://bytekit.com/llms.txt — every docs page is available as markdown by appending .md

GET
/v1/bulk/{id}

Authorization

AuthorizationRequiredBearer <token>

API key. Manage keys from the dashboard at app.bytekit.com.

In: header

Path Parameters

idRequiredstring
Pattern: "^bulk_"
curl https://api.bytekit.com/v1/bulk/{id} \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Successful response.

{
  "id": "bulk_01j9abc123",
  "status": "processing",
  "total": 0,
  "completed": 0,
  "failed": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "total_credits_charged": 0,
  "total_billed_bytes": 0,
  "estimated_credits": 0,
  "webhook_url": "string"
}

POST /v1/bulkCreate mixed bulk job

Enqueues screenshots or scrapes in a single batch. Provide `urls` (simple list) or `items` (per-item config), not both. Webhook deliveries include `X-ByteKit-Event: bulk.completed` so receivers can dispatch on the header without parsing the body shape. The body follows `BulkCompletedWebhook`: at most 500 complete items and 1 MiB, followed by cursor recovery through the existing mixed-item route whenever `recovery_required` is true. **Limits:** request bodies are guarded in a two-tier shape. A streamed body with no `Content-Length` header is capped at 4 MB before your API key is checked; a body that declares `Content-Length` is instead bounded there by a 32 MB fail-safe (not the real limit — see below), since that branch reads nothing until your key is verified. Once your key is verified, a second check re-gates the body against your account's own `max_bulk_size` (at this endpoint's richer per-item override budget), which reaches 28.7 MB for the largest documented account. A standard-plan account's effective ceiling is 4 MB; either tier's overrun returns a `400` with error code `request_too_large`.

DELETE /v1/bulk/{id}Cancel a bulk job

Cancels an in-flight bulk job: drains its still-queued (pending) child jobs and refunds the quota held for exactly those drained children. Children already completed, failed, or in progress are untouched and keep their charge. Idempotent — cancelling an already-terminal job (completed, failed, or cancelled) is a no-op that returns 200 with the job's real, unchanged status and refunds nothing.