API ReferenceBulk

List bulk job items

Returns the bulk job's items, discriminated by type.

Downloading item artifacts. For a completed item with a storage key, image_url (type: screenshot) and both content_url and markdown_url (type: scrape) are pre-signed URLs, minted fresh on every read of this endpoint and valid for 600 seconds (10 minutes) — the same signing lifetime as content_url on GET /v1/fetch/bulk/{id}. Download inside that window, or re-poll this endpoint for a fresh signature.

When no signature is minted. Three cases mint none: an item that is not completed, a completed item with no storage key, and a completed item whose object could not be signed — during an object-storage outage, for instance. In all three the item's stored value is returned unchanged: null while nothing has been stored, and otherwise a private, unsigned object-storage URL that answers 401. These fields are neither nulled nor flagged in that case, so treat an artifact URL as usable only once you have downloaded it, and re-poll for a fresh signature otherwise. artifact_warnings and its artifact_unavailable code describe the sibling artifacts object on type: scrape items only — they say nothing about image_url, content_url, or markdown_url.

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

GET
/v1/bulk/{id}/screenshots

Authorization

AuthorizationRequiredBearer <token>

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

In: header

Path Parameters

idRequiredstring
Pattern: "^bulk_"

Query Parameters

cursorstring

Opaque per-type seek cursor returned by the preceding page. It is bound to this bulk id, this mixed recovery route, and the exact status filter; cross-scope cursors return 422.

limitinteger

Maximum rows selected per requested item type; the 16-MiB response bound may stop sooner.

Default: 100Minimum: 1Maximum: 500
statusstring

Optional item-status filter. A cursor may be reused only with the same filter.

Value in: "pending" | "processing" | "completed" | "failed" | "cancelled"
curl https://api.bytekit.com/v1/bulk/{id}/screenshots \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Successful response.

{
  "bulk_id": "bulk_01j9abc123",
  "total": 0,
  "next_cursor": "string",
  "has_more": true,
  "job_counters": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "items": [
    {
      "type": "screenshot",
      "id": "string",
      "status": "pending",
      "url": "http://example.com",
      "credits_charged": 0,
      "billing": {
        "raw_bytes": 1024,
        "factors": [
          {
            "name": "endpoint",
            "value": 1.5,
            "reason": "scrape_md"
          }
        ],
        "multiplier": 0.75,
        "billed_bytes": 768
      },
      "error_code": "string",
      "error_message": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "completed_at": "2019-08-24T14:15:22Z",
      "image_url": "string",
      "page_title": "string",
      "format": "string",
      "video_url": "string",
      "content_url": "string",
      "content_type": "string",
      "content_length": 0,
      "markdown": "string",
      "markdown_url": "string",
      "artifacts": {
        "raw": "string",
        "markdown": "string",
        "json": {},
        "links": {},
        "images": {}
      },
      "artifact_warnings": [
        {
          "code": "lossy_table",
          "message": "string",
          "element": "string"
        }
      ]
    }
  ]
}

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.

Monitors

Monitors API — endpoints, requests, and responses.