---
title: "Batch Requests"
method: POST
path: "/v1/batch"
tags: ["Batch"]
---

# Batch Requests

`POST /v1/batch`

## Request

- Base URL: `https://apidirect.io`
- URL: `https://apidirect.io/v1/batch`
- Auth: API key in header `X-API-Key`

Run up to 100 API calls in one request, in any mix of endpoints. Items run concurrently server-side and each returns its own status and body, in input order. The JSON body can be at most 1 MB. Allow up to 13 minutes for a large batch to finish.

Batching is free: each item bills under its own endpoint at its normal rate and uses that endpoint's free tier, exactly like a direct call. Items the batch could not get to return `status: 0` and are never billed.

## Request body

- BatchRequest
  - `requests` BatchRequestItem[], required: The calls to run, 1 to 100 of them, in any mix of endpoints.
    - `endpoint` string, required: The endpoint path to call, for example `/v1/twitter/user`. Every endpoint except `/v1/web/ai-mode` and `/v1/time` is allowed.
    - `params` object: The query parameters the endpoint takes when called directly. Values must be strings or numbers (send booleans as "true").
    - `tag` string: Optional label echoed back on this item's result.

## Response `200`

Per-item results. Check each item's `status`: one item failing never fails the batch.

- BatchResponse
  - `results` BatchResult[]: One result per request item, in input order.
    - `index` integer: Position of the item in `requests`.
    - `endpoint` string: The endpoint the item called.
    - `tag` string, nullable: The item's tag, when one was sent.
    - `status` integer: The item's HTTP status: 2xx on success, the endpoint's normal 4xx/5xx on error, or 0 when the item was not attempted (never billed).
    - `body` object: Exactly what the endpoint returns when called directly, or its error body.
  - `summary` object
    - `total` integer: Number of items in the batch.
    - `succeeded` integer: Items that returned 2xx.
    - `failed` integer: Items that did not succeed.
    - `duration_ms` integer: Total batch execution time.

## Other responses

- `400`: Invalid batch body (`invalid_parameter`), or the call did not use an `X-API-Key` header (`unsupported_auth`).
- `401`: Missing or invalid API key (`missing_api_key`, `invalid_api_key`).
- `403`: Account blocked after a failed payment (`account_blocked`).
- `413`: Request body larger than 1 MB (`payload_too_large`). Split the batch into smaller ones.
- `429`: Too many batches running at once for this account (`concurrency_limit_exceeded`).
- `500`: Internal server error.

---

[API](https://skmtc.dev/apidirect/apis/api-direct.md) · [All operations](https://skmtc.dev/apidirect/apis/api-direct/llms.txt) · [OpenAPI document](https://skmtc.dev/apidirect/apis/api-direct/revisions/fa8c68d70bd0?raw)