Skip to main content
Batch endpoints let you submit multiple items in a single API call and receive per-item results. Instead of making one request per item — paying the network round-trip cost each time — you pack up to hundreds of items into a single POST and get back a structured response that maps each input to its own status and data. This is especially useful for bulk lookups, inventory enrichment pipelines, and any workflow that would otherwise serialize many individual calls.
The batch framework is fully wired — authentication, scope enforcement, rate limiting, quota metering, idempotency, and plan-capped size limits are all active. Per-item business logic for the currently available batch endpoints is in active development; live requests return stub responses.

​
Available batch endpoints

EndpointScopeStatus
POST /api/v1/intelligence/batchintelligence.readAvailable (stub)
POST /api/v1/signals/batchsignals.readAvailable (stub)
POST /api/v1/enrichment/batchenrichment.readAvailable (stub)

​
Request shape

Every batch endpoint accepts the same JSON body structure. The requests field is an array of item objects — the shape of each item is endpoint-specific, but the envelope is always the same. 
curl -s -X POST "https://api.8bitedge.com/api/v1/signals/batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      { "id": 1 },
      { "id": 2 }
    ]
  }' | jq
Body fieldTypeNotes
requestsarrayOne or more item objects. Count is capped by your plan’s max_batch_size.
Sending an empty requests array, or omitting it entirely, returns 422 validation_failed. Every batch call must include at least one item.

​
Response shape

The HTTP status code tells you the overall outcome of the batch:
  • 200 OK — every item in the batch succeeded.
  • 207 Multi-Status — at least one item failed. The top-level HTTP status is 207 regardless of how many items succeeded or failed.
Each element in the data array corresponds to one item from your requests array, in the same order. Successful items carry a status: 200 and a data object; failed items carry a status code and an error object. 
{
  "data": [
    {
      "status": 200,
      "data": { "echo": { "id": 1 }, "note": "stub" }
    },
    {
      "status": 422,
      "error": {
        "code": "validation_failed",
        "message": "...",
        "details": {}
      }
    }
  ],
  "meta": {
    "batch": {
      "total": 2,
      "succeeded": 1,
      "failed": 1
    }
  }
}
The meta.batch summary gives you total, succeeded, and failed counts so you can detect partial failures without inspecting every item.

​
Batch size limits

Your plan determines the maximum number of items you can include in a single batch request.
PlanMax batch size
Free10
Starter50
Pro100
Enterprise250
If you send more items than your plan allows, the API rejects the entire request before processing any items: 
{
  "error": {
    "code": "batch_too_large",
    "message": "Batch exceeds the maximum allowed size for your plan.",
    "details": {
      "max_items": 50,
      "received": 75
    }
  }
}
The response is 422 batch_too_large. Split your payload into smaller chunks and retry each one separately.

​
Idempotent batch requests

You can make any batch request safely retryable by sending an Idempotency-Key header with a unique value — typically a UUID generated client-side. If your request fails at the network level before you receive a response, you can replay the exact same key and body to retrieve the original result without risk of double-processing. 
KEY=$(uuidgen)

# First attempt
curl -s -X POST "https://api.8bitedge.com/api/v1/signals/batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{ "requests": [ { "id": 1 } ] }' | jq

# Safe retry on network error — same key + same body returns the stored result
curl -s -D - -X POST "https://api.8bitedge.com/api/v1/signals/batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{ "requests": [ { "id": 1 } ] }' -o /dev/null | grep -i idempotency-replayed
When the second request replays a stored result, the response includes the header Idempotency-Replayed: true. Important behaviors to know:
  • Replaying the same key with a different payload returns 422 idempotency_key_reuse. The key is bound to the original body.
  • If the original request is still in flight, a replay returns 409 idempotency_conflict. Wait and retry.
  • Stored results expire after 24 hours. After expiry, the key can be reused freely.
Generate a fresh uuidgen key for every logical batch operation. Reusing keys across different operations is the most common source of idempotency_key_reuse errors.

​
Metering

Each item in the requests array counts as one API usage unit toward your monthly quota. A batch of 50 items consumes 50 units — the same as 50 individual requests. Batching reduces round-trips and latency, but does not reduce quota consumption.
If your batch is rejected at the request level — for example, with 422 batch_too_large or 403 insufficient_scope — no items are metered and your quota is not charged.

​
Next steps

Idempotency

How idempotency keys work across the full API, including expiry and conflict handling.

Plans and Limits

Full breakdown of rate limits, monthly quotas, and batch size caps per plan.

Signals API Reference

Reference for the /signals category endpoints, including the batch operation.

Intelligence API Reference

Reference for the /intelligence category endpoints, including the batch operation.