Batch jobs¶
For long inventories: up to 5,000 devices or 1,000 Windows hosts per job. You submit once, BreachSpider works through the list in the background, and you read the results page by page (or get a signed callback when the job finishes). Each result is exactly what the matching synchronous call returns for that device or host.
| Method and path | Purpose |
|---|---|
POST /api/v1/batches | Devices: the body of POST /api/v1/assets/correlate-cves, plus an optional callback_url |
POST /api/v2/batches | Windows hosts: the body of POST /api/v2/assets/check-windows, plus an optional callback_url |
GET /api/v1/batches/{job_id} (or /api/v2/...) | Status, progress and timestamps; a summary once the job has finished |
GET /api/v1/batches/{job_id}/results?cursor=&limit= | Results in submission order, 50 per page by default, at most 200 |
DELETE /api/v1/batches/{job_id} | Cancel: the key that submitted it, or an admin key |
Who can use it: API keys with batch jobs turned on (ask us to enable it for your key). Browser sessions, demo tokens and trial keys cannot. Without access every batch route answers 404.
Idempotency: send an Idempotency-Key header (any unique string) with every submit. Sending the same key again within 24 hours returns the original job instead of creating a second one, so a retry after a timeout is never billed twice.
curl -X POST https://breachspider.com/api/v1/batches \
-H "Authorization: Bearer $BREACHSPIDER_API_KEY" \
-H "Idempotency-Key: inventory-2026-11-08-plant-a" \
-H "Content-Type: application/json" \
-d '{"assets": [{"asset_id": "PLC-01", "vendor": "Siemens", "product": "S7-1200", "version": "4.2.0"}]}'
The answer is 202 Accepted with the job id, "status": "queued" and the status and results addresses (also in the Location header).
Status¶
status is one of queued, running, succeeded, partial (some items failed), failed (none succeeded) or cancelled. progress gives done, failed and total. Results are available while a job runs; each page has a next_cursor until the last.
Limits and billing¶
Validation, your key's rate limit and metering run when you submit, in the same order as the synchronous call. The whole job is reserved at submit; units for items that are never processed (for example after a cancel) are refunded to that month. A job larger than the limit is refused with 413.
Callback when the job finishes¶
Create a batch webhook secret for the key in the web app (Integrations > API keys; it is shown once), then send callback_url with the job. When the job finishes, BreachSpider posts:
{"event": "batch.completed", "job_id": "…", "status": "succeeded"}
with the header BreachSpider-Signature: t=<unix time>,v1=<hex>. The signature is an HMAC-SHA256 of "<t>." + body with your secret; after you rotate the secret, both the old and the new one sign for 24 hours. Check the signature and the time before trusting the call. Delivery is retried 5 times (after 1, 2, 4, 8 and 16 minutes). The callback address must be a public HTTPS address; it is checked when you submit and again when we send.
Data handling¶
Inputs and results are encrypted at rest; each input is erased once it has been processed, and jobs expire after 30 days. Another organization's job answers 404. With the Python SDK or the MCP server you do not need to call these routes yourself.