Skip to main content
POST
/
batches
Create a batch
curl --request POST \
  --url https://api.valarhq.ai/v1/batches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "endpoint": "/v1/responses",
  "label": "my-batch-job",
  "requests": [
    {
      "custom_id": "my-first-request",
      "params": {
        "model": "zai-org/GLM-5.1-FP8",
        "max_output_tokens": 1024,
        "input": [
          {
            "role": "user",
            "content": "Hello, world!"
          }
        ]
      }
    },
    {
      "custom_id": "my-second-request",
      "params": {
        "model": "zai-org/GLM-5.1-FP8",
        "max_output_tokens": 1024,
        "input": [
          {
            "role": "user",
            "content": "Hello again!"
          }
        ]
      }
    }
  ]
}
'
{
  "id": "batch_abc123",
  "request_counts": 2,
  "created_at": 1741564800,
  "label": "my-batch-job"
}
Coming soon. The Batches API isn’t generally available yet. For large workloads today, run requests asynchronously with background=True — see Sending requests at scale.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string

Lets you retry safely. Valar records a reservation under the combination of organization, API key, and Idempotency-Key, so sending the same value again hands back the stored response rather than running inference a second time. Values can be up to 255 characters. See Idempotent Requests for the complete rules.

Maximum string length: 255

Body

application/json
endpoint
enum<string>
required

Which API endpoint every request in the batch targets. Right now /v1/responses is the only valid choice.

Available options:
/v1/responses
requests
object[]
required

The requests that make up the batch, from 1 up to 100,000 of them. The combined request body has to stay under 256 MB.

Required array length: 1 - 100000 elements
label
string

An optional name for the batch. Use letters and digits, optionally with hyphens and underscores, up to 128 characters.

Maximum string length: 128
Pattern: ^[a-zA-Z0-9_-]+$

Response

The batch was created.

id
string
required

The batch's unique ID.

request_counts
integer
required

How many requests the batch contains.

created_at
integer
required

When the batch was created, as a Unix timestamp.

label
string

The label you gave the batch, when one was set.