spicrawlspicrawlDocs
Batch

Re-run a job's failed items

Resets every item with status `failed` back to queued and re-dispatches it; takes no body.

Requires scope: batch

POST
/v1/batch/{batchID}/retry

Resets every item with status failed back to queued and re-dispatches it; takes no body. Succeeded, cancelled and skipped items are never re-run. If the job was terminal it goes back to queued and finished_at is cleared; if it is still running, the reset items join the current run. Item attempts is NOT reset. No items failed → a no-op returning the job unchanged with items_reset: 0. A failed item whose hold was already returned to the monthly allowance holds its price again first; 402 if the allowance cannot cover it, and then nothing is reset. Next: poll GET /v1/batch/{batchID} again.

Authorization

bearerAuth
AuthorizationBearer <token>

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

batchID*string

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.

Length26 <= length <= 36

Response Body

application/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/retry"
{  "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_reset": 0,  "items_dispatched": 0}

Cancel a batch job POST

Requests cancellation of a `queued`, `running`, `paused` or `cancelling` job; takes no body.

Append items to an open job POST

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