Append items to an open job
Adds items to a job created with `open: true`. Same body shape as batchCreate: `urls` or `items`, at most 10,000 per call; a job holds at most 100,000 items across all appends (exceeding it is a 400).
Requires scope: batch
Adds items to a job created with open: true. Same body shape as batchCreate: urls or items, at most 10,000
per call; a job holds at most 100,000 items across all appends (exceeding it is a 400). New items get seq
numbers continuing from the job's current total.
Only per-item values are stored: a new item runs with the job's ORIGINAL job-level parameters plus its own
overrides. Top-level scrape parameters in this body are used only to validate the new items and are otherwise
discarded; run controls (name, concurrency, priority, max_attempts, failure_threshold, credit_budget,
webhook_endpoint_id, open) are accepted and ignored. Appended items are held against the monthly allowance
exactly like submitted ones (402 if it cannot cover them, and then nothing is added); estimated_credits
stays the submission's and is not updated.
409 when the job is closed (never opened, or already closed). When finished appending, call
POST /v1/batch/{batchID}/close.
Authorization
bearerAuth Authorization: Bearer <key>. Read the key from the SPICRAWL_API_KEY environment
variable; never hard-code or log it. spicrawl_test_… keys can never spend live
credits. Scopes: scrape, batch, sessions (granted by default), browser
and read (granted deliberately). A missing scope is 403 ERR::AUTH::INSUFFICIENT_SCOPE naming the scope.
In: header
Path Parameters
The job id (26-character ULID as returned). The 32/36-character UUID form of the same id is also accepted. A malformed id and another tenant's id both answer 404.
26 <= length <= 36Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Body of POST /v1/batch (and of POST /v1/batch/{batchID}/items). Exactly one of urls or items must be non-empty.
Top-level BatchScrapeParams fields are job-wide defaults. A top-level url is rejected with 400 — put targets in
urls or items[].url. Unknown fields are a 400. Must be ≤ 1 MiB; ≤ 10,000 targets.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X POST "https://example.com/v1/batch/01J9Z6T3W9E21T5TZARVJRVN5C/items" \ -H "Content-Type: application/json" \ -d '{ "items": [ { "url": "https://example.com/discovered/17", "external_id": "page-17" }, { "url": "https://example.com/discovered/18" } ] }'{ "job": { "id": "01J9Z6T3W9E21T5TZARVJRVN5C", "project_id": "01J8X2M4C7Q1H5V9P3R6T8W0YB", "name": "catalog-2026-09-22", "status": "running", "status_url": "/v1/batch/01J9Z6T3W9E21T5TZARVJRVN5C", "results_url": "/v1/batch/01J9Z6T3W9E21T5TZARVJRVN5C/results", "params": { "js_render": true, "proxy_country": "us", "credit_budget_micro": 8000000 }, "total_items": 2, "concurrency": 20, "priority": 100, "max_attempts": 3, "estimated_credits": 8, "estimated_credits_micro": 8000000, "progress": { "total": 2, "completed": 1, "succeeded": 1, "failed": 0, "cancelled": 0, "skipped": 0, "remaining": 1, "percent_complete": 50, "credits_charged": 4, "credits_charged_micro": 4000000, "bytes": 326000 }, "submitted_at": "2026-09-22T06:41:12Z", "started_at": "2026-09-22T06:41:13Z", "results_expire_at": "2026-09-25T06:41:12Z" }, "items_added": 1, "items_dispatched": 0}