> ## Documentation Index
> Fetch the complete documentation index at: https://docs.8bitedge.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Submit and manage batch requests with the 8bitedge API
> Send multiple items in a single 8bitedge API call using batch endpoints. Supports mixed success/failure responses and idempotent retries.
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
| Endpoint | Scope | Status |
| --------------------------------- | ------------------- | ---------------- |
| `POST /api/v1/intelligence/batch` | `intelligence.read` | Available (stub) |
| `POST /api/v1/signals/batch` | `signals.read` | Available (stub) |
| `POST /api/v1/enrichment/batch` | `enrichment.read` | Available (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.
```bash theme={null}
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 field | Type | Notes |
| ---------- | ----- | -------------------------------------------------------------------------- |
| `requests` | array | One 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.
```json theme={null}
{
"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.
| Plan | Max batch size |
| ---------- | -------------- |
| Free | 10 |
| Starter | 50 |
| Pro | 100 |
| Enterprise | 250 |
If you send more items than your plan allows, the API rejects the entire request before processing any items:
```json theme={null}
{
"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.
```bash theme={null}
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
How idempotency keys work across the full API, including expiry and conflict handling.
Full breakdown of rate limits, monthly quotas, and batch size caps per plan.
Reference for the `/signals` category endpoints, including the batch operation.
Reference for the `/intelligence` category endpoints, including the batch operation.