Create a batch

curl --request POST \
  --url https://api.valarhq.ai/v1/batches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input_file_id": "file-abc123",
  "endpoint": "/v1/chat/completions",
  "completion_window": "24h",
  "metadata": {
    "label": "my-batch-job"
  }
}
'

import requests

url = "https://api.valarhq.ai/v1/batches"

payload = {
    "input_file_id": "file-abc123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h",
    "metadata": { "label": "my-batch-job" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    input_file_id: 'file-abc123',
    endpoint: '/v1/chat/completions',
    completion_window: '24h',
    metadata: {label: 'my-batch-job'}
  })
};

fetch('https://api.valarhq.ai/v1/batches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.valarhq.ai/v1/batches",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'input_file_id' => 'file-abc123',
    'endpoint' => '/v1/chat/completions',
    'completion_window' => '24h',
    'metadata' => [
        'label' => 'my-batch-job'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.valarhq.ai/v1/batches"

	payload := strings.NewReader("{\n  \"input_file_id\": \"file-abc123\",\n  \"endpoint\": \"/v1/chat/completions\",\n  \"completion_window\": \"24h\",\n  \"metadata\": {\n    \"label\": \"my-batch-job\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.valarhq.ai/v1/batches")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input_file_id\": \"file-abc123\",\n  \"endpoint\": \"/v1/chat/completions\",\n  \"completion_window\": \"24h\",\n  \"metadata\": {\n    \"label\": \"my-batch-job\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.valarhq.ai/v1/batches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input_file_id\": \"file-abc123\",\n  \"endpoint\": \"/v1/chat/completions\",\n  \"completion_window\": \"24h\",\n  \"metadata\": {\n    \"label\": \"my-batch-job\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "validating",
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "created_at": 1741564800,
  "metadata": {
    "label": "my-batch-job"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<string>"
  }
}

Batches

Create a batch

Start processing a previously uploaded JSONL file of requests. Upload the file first with Upload a file using purpose: batch. Each line of the file is one request:

{"custom_id": "req-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "zai-org/GLM-5.2", "messages": [{"role": "user", "content": "Hello!"}]}}

A batch holds up to 10,000 requests, and each line can be up to 28 MiB — enough for a maximum-size 20 MB image, which takes about 26.7 MiB once base64-encoded. The line size is a transport limit; each request must also fit the context window of the model it names, which is a separate and often much tighter bound — read context_length from List supported models and size your requests against it. A request over the window is accepted with the file and fails when it runs. A file with more than 10,000 requests fails the whole batch after creation (status: failed). A line that fails validation is rejected on its own and counted in request_counts.failed; the rest of the batch keeps running.

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 '
{
  "input_file_id": "file-abc123",
  "endpoint": "/v1/chat/completions",
  "completion_window": "24h",
  "metadata": {
    "label": "my-batch-job"
  }
}
'

import requests

url = "https://api.valarhq.ai/v1/batches"

payload = {
    "input_file_id": "file-abc123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h",
    "metadata": { "label": "my-batch-job" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    input_file_id: 'file-abc123',
    endpoint: '/v1/chat/completions',
    completion_window: '24h',
    metadata: {label: 'my-batch-job'}
  })
};

fetch('https://api.valarhq.ai/v1/batches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.valarhq.ai/v1/batches",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'input_file_id' => 'file-abc123',
    'endpoint' => '/v1/chat/completions',
    'completion_window' => '24h',
    'metadata' => [
        'label' => 'my-batch-job'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.valarhq.ai/v1/batches"

	payload := strings.NewReader("{\n  \"input_file_id\": \"file-abc123\",\n  \"endpoint\": \"/v1/chat/completions\",\n  \"completion_window\": \"24h\",\n  \"metadata\": {\n    \"label\": \"my-batch-job\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.valarhq.ai/v1/batches")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input_file_id\": \"file-abc123\",\n  \"endpoint\": \"/v1/chat/completions\",\n  \"completion_window\": \"24h\",\n  \"metadata\": {\n    \"label\": \"my-batch-job\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.valarhq.ai/v1/batches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input_file_id\": \"file-abc123\",\n  \"endpoint\": \"/v1/chat/completions\",\n  \"completion_window\": \"24h\",\n  \"metadata\": {\n    \"label\": \"my-batch-job\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "validating",
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "created_at": 1741564800,
  "metadata": {
    "label": "my-batch-job"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<string>"
  }
}

Authorizations

Authorization

string

header

required

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

Body

application/json

input_file_id

string

required

The ID of an uploaded purpose: batch JSONL file holding the requests.

endpoint

enum<string>

required

The API endpoint every request in the batch targets. Must match the url on each line.

Available options:

/v1/chat/completions,

/v1/responses

completion_window

enum<string>

required

Pass 24h, the OpenAI-compatible value. Valar schedules the batch against its own promised SLAs.

Available options:

24h

metadata

object

Optional key-value metadata stored on the batch, echoed back on every read.

Show child attributes

Response

The batch was created and is validating.

string

required

The batch's unique ID.

object

enum<string>

required

Available options:

batch

endpoint

enum<string>

required

The API endpoint every request in the batch targets.

Available options:

/v1/chat/completions,

/v1/responses

input_file_id

string

required

The uploaded JSONL file the batch was created from.

completion_window

string

required

The completion window the batch was submitted with. 24h is the OpenAI-compatible value; Valar processes batches against its own promised SLAs.

status

enum<string>

required

Where the batch currently stands. A new batch starts in validating, moves to in_progress while its requests run, and settles in a terminal state.

Available options:

validating,

in_progress,

finalizing,

completed,

failed,

expired

request_counts

object

required

Show child attributes

created_at

integer

required

When the batch was created, as a Unix timestamp.

output_file_id

string

Once the batch completes, the file holding one JSONL result line per request. Download it with Get file content.

error_file_id

string

When any line failed, the file holding one JSONL error line per failed request - validation rejections included. Absent when every request succeeded.

metadata

object

The metadata you attached at create time, if any.

Show child attributes

Responses

Chat completions

Files

Batches

Models

Usage

Models API

Responses API

Chat Completions API

Batches API

Files API

Create a batch

Authorizations

Body

Response