Create Batch

POST

batches

Create Batch

curl --request POST \
  --url https://api.neosantara.xyz/v1/batches \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "input_file_id": "<string>",
  "endpoint": "<string>",
  "completion_window": "<string>",
  "metadata": {}
}
'

import requests

url = "https://api.neosantara.xyz/v1/batches"

payload = {
    "input_file_id": "<string>",
    "endpoint": "<string>",
    "completion_window": "<string>",
    "metadata": {}
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    input_file_id: '<string>',
    endpoint: '<string>',
    completion_window: '<string>',
    metadata: {}
  })
};

fetch('https://api.neosantara.xyz/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.neosantara.xyz/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' => '<string>',
    'endpoint' => '<string>',
    'completion_window' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$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.neosantara.xyz/v1/batches"

	payload := strings.NewReader("{\n  \"input_file_id\": \"<string>\",\n  \"endpoint\": \"<string>\",\n  \"completion_window\": \"<string>\",\n  \"metadata\": {}\n}")

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

	req.Header.Add("x-api-key", "<api-key>")
	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.neosantara.xyz/v1/batches")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input_file_id\": \"<string>\",\n  \"endpoint\": \"<string>\",\n  \"completion_window\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.neosantara.xyz/v1/batches")

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

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input_file_id\": \"<string>\",\n  \"endpoint\": \"<string>\",\n  \"completion_window\": \"<string>\",\n  \"metadata\": {}\n}"

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

{
  "id": "<string>",
  "object": "<string>",
  "endpoint": "<string>",
  "errors": {},
  "input_file_id": "<string>",
  "completion_window": "<string>",
  "status": "<string>",
  "output_file_id": {},
  "error_file_id": {},
  "created_at": 123,
  "in_progress_at": {},
  "expires_at": 123,
  "finalizing_at": {},
  "completed_at": {},
  "failed_at": {},
  "expired_at": {},
  "cancelling_at": {},
  "cancelled_at": {},
  "request_counts": {
    "total": 123,
    "completed": 123,
    "failed": 123
  },
  "metadata": {}
}

Save 50% on Batch Processing

Batch API offers 50% cost savings compared to standard API calls. Perfect for processing large volumes of requests asynchronously.

Free Tier Limitation: Batch API is only available for Basic tier and above. Upgrade your plan to unlock batch processing.

Create a new batch job for asynchronous processing of multiple API requests.

string

required

The ID of an uploaded file that contains the requests for this batch. The file must be uploaded with purpose="batch" and be in valid JSONL format.

string

required

The endpoint to be used for all requests in the batch. Currently supported endpoints:

/v1/chat/completions - For chat completion requests
/v1/embeddings - For embedding generation
/v1/responses - For response generation

string

default:"24h"

The time frame within which the batch should be processed. Currently only 24h is supported.

object

Optional custom metadata for the batch. Can contain any key-value pairs for tracking purposes.

Returns

string

A unique identifier for the batch job (e.g., batch-abc123).

string

The object type, which is always batch.

string

The API endpoint that will be used for all requests in the batch.

object or null

Any errors encountered during batch processing. Will be null if no errors.

string

The ID of the input file containing batch requests.

string

The time window for batch completion.

string

The current status of the batch. Possible values:

validating - The input file is being validated
in_progress - The batch is being processed
finalizing - The batch is being finalized
completed - The batch has completed successfully
failed - The batch has failed
expired - The batch has expired
canceled - The batch was canceled

string or null

The ID of the file containing successful batch results. Available when status is completed.

string or null

The ID of the file containing failed requests. Available when there are errors.

integer

The Unix timestamp (in seconds) of when the batch was created.

integer or null

The Unix timestamp when the batch started processing.

integer

The Unix timestamp when the batch will expire.

integer or null

The Unix timestamp when the batch started finalizing.

integer or null

The Unix timestamp when the batch completed.

integer or null

The Unix timestamp when the batch failed.

integer or null

The Unix timestamp when the batch expired.

integer or null

The Unix timestamp when cancellation was initiated.

integer or null

The Unix timestamp when the batch was cancelled.

object

Statistics about the requests in the batch.

Show request_counts properties

integer

Total number of requests in the batch.

integer

Number of requests that completed successfully.

integer

Number of requests that failed.

object

Custom metadata associated with the batch.

{
  "id": "batch-abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-xyz789",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1699564800,
  "in_progress_at": null,
  "expires_at": 1699651200,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 100,
    "completed": 0,
    "failed": 0
  },
  "metadata": {
    "project": "data-analysis",
    "batch_type": "daily_processing"
  }
}

{
  "error": {
    "message": "Batch API is not available for Free tier. Please upgrade to Basic or higher to unlock batch processing with 50% cost savings.",
    "type": "permission_denied_error",
    "code": "batch_api_not_allowed",
    "upgrade_url": "https://app.neosantara.xyz/billing"
  }
}

{
  "error": {
    "message": "Missing required field: input_file_id",
    "type": "invalid_request_error",
    "param": "input_file_id",
    "code": "missing_required_field"
  }
}

{
  "error": {
    "message": "Invalid endpoint. Supported endpoints: /v1/chat/completions, /v1/embeddings, /v1/responses",
    "type": "invalid_request_error",
    "param": "endpoint",
    "code": "invalid_endpoint"
  }
}

{
  "error": {
    "message": "Input file not found or invalid purpose. File must be uploaded with purpose=\"batch\"",
    "type": "invalid_request_error",
    "param": "input_file_id",
    "code": "invalid_input_file"
  }
}

{
  "error": {
    "message": "Concurrent batch limit reached (5). Please wait for existing batches to complete.",
    "type": "rate_limit_error",
    "code": "concurrent_batches_limit",
    "current_batches": 5,
    "limit": 5
  }
}

Last modified on December 7, 2025

Create Batch

curl --request POST \
  --url https://api.neosantara.xyz/v1/batches \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "input_file_id": "<string>",
  "endpoint": "<string>",
  "completion_window": "<string>",
  "metadata": {}
}
'

import requests

url = "https://api.neosantara.xyz/v1/batches"

payload = {
    "input_file_id": "<string>",
    "endpoint": "<string>",
    "completion_window": "<string>",
    "metadata": {}
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    input_file_id: '<string>',
    endpoint: '<string>',
    completion_window: '<string>',
    metadata: {}
  })
};

fetch('https://api.neosantara.xyz/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.neosantara.xyz/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' => '<string>',
    'endpoint' => '<string>',
    'completion_window' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$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.neosantara.xyz/v1/batches"

	payload := strings.NewReader("{\n  \"input_file_id\": \"<string>\",\n  \"endpoint\": \"<string>\",\n  \"completion_window\": \"<string>\",\n  \"metadata\": {}\n}")

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

	req.Header.Add("x-api-key", "<api-key>")
	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.neosantara.xyz/v1/batches")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input_file_id\": \"<string>\",\n  \"endpoint\": \"<string>\",\n  \"completion_window\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.neosantara.xyz/v1/batches")

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

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input_file_id\": \"<string>\",\n  \"endpoint\": \"<string>\",\n  \"completion_window\": \"<string>\",\n  \"metadata\": {}\n}"

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

{
  "id": "<string>",
  "object": "<string>",
  "endpoint": "<string>",
  "errors": {},
  "input_file_id": "<string>",
  "completion_window": "<string>",
  "status": "<string>",
  "output_file_id": {},
  "error_file_id": {},
  "created_at": 123,
  "in_progress_at": {},
  "expires_at": 123,
  "finalizing_at": {},
  "completed_at": {},
  "failed_at": {},
  "expired_at": {},
  "cancelling_at": {},
  "cancelled_at": {},
  "request_counts": {
    "total": 123,
    "completed": 123,
    "failed": 123
  },
  "metadata": {}
}

Using the APIs

API reference

Save 50% on Batch Processing

Returns

Save 50% on Batch Processing

​Returns

Returns