API ReferenceBulk

Create 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.

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

POST
/v1/bulk

Authorization

AuthorizationRequiredBearer <token>

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

In: header

Request Body

application/jsonRequired
urlsarray<string>

Simple URL list. Provide urls OR items, not both.

itemsarray<object>

Per-item configs. Provide urls OR items, not both.

defaultsobject

Default behaviour applied to every entry unless the item overrides it.

webhook_urlRequiredstring

Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported)

Pattern: "^https://"Format: "uri"
webhook_secretstring

HMAC secret used to sign webhook deliveries. Each delivery carries X-Webhook-Timestamp and X-Webhook-Signature (sha256= + the hex HMAC-SHA256 of timestamp.body). See https://bytekit.com/docs/guides/webhooks for verification code.

metadataobject

Arbitrary key-value metadata. Max 4096 bytes when JSON-serialized.

curl -X POST https://api.bytekit.com/v1/bulk \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "url": "https://example.com",
      "type": "screenshot",
      "device": "mobile",
      "format": "png",
      "quality": 90,
      "full_page": true,
      "dark_mode": true,
      "viewport": {
        "width": 1280,
        "height": 720
      }
    },
    {
      "url": "https://example.org",
      "type": "scrape",
      "formats": [
        "markdown",
        "raw"
      ],
      "include_html": true,
      "wait_until": "networkidle",
      "wait_for_selector": "#main",
      "delay_ms": 500,
      "metadata": {
        "item_tag": "hero"
      }
    }
  ],
  "defaults": {
    "type": "screenshot",
    "device": "desktop",
    "country": "US",
    "formats": [
      "raw"
    ],
    "device_scale_factor": 2
  },
  "metadata": {
    "campaign": "q3"
  },
  "webhook_url": "https://hooks.example.com/bytekit"
}'

Bulk job accepted.

{
  "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"
}

GET /v1/bulkList bulk jobs

Returns the caller's bulk jobs, most recent first, one cursor-paginated page at a time. Optionally filter to a single status; when omitted, jobs of every status are returned. `status` narrows the set and the cursor addresses a position inside that already-ordered, already-filtered set, so the two can be combined in one request. Follow `next_cursor` while `has_more` is true.

GET /v1/bulk/{id}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`.