API ReferenceBatches

Batches

Create and manage batch processing jobs. Batches allow you to send a large number of requests in a single file and process them asynchronously at a lower cost. This is ideal for bulk tasks like classification, summarization, or embedding generation where immediate responses are not required.

Endpoints

POST https://api.tensoras.ai/v1/batches
GET  https://api.tensoras.ai/v1/batches/{batch_id}
GET  https://api.tensoras.ai/v1/batches

Authentication

Authorization: Bearer tns_your_key_here

Create Batch

Submit a batch of requests for asynchronous processing. The input file must be a JSONL file where each line is a valid API request. Upload the file first using the Files API.

Request

POST /v1/batches
ParameterTypeRequiredDescription
input_file_idstringYesThe ID of the uploaded JSONL file containing the batch requests.
endpointstringYesThe API endpoint for the batch. One of /v1/chat/completions, /v1/completions, /v1/embeddings.
completion_windowstringYesThe time window for batch completion. Currently only "24h" is supported.
metadataobjectNoOptional key-value metadata to attach to the batch.

Input File Format

Each line of the JSONL file must contain a request object with the following fields:

{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "llama-3.3-70b", "messages": [{"role": "user", "content": "Summarize this article: ..."}], "max_tokens": 256}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "llama-3.3-70b", "messages": [{"role": "user", "content": "Classify this text: ..."}], "max_tokens": 64}}
FieldTypeDescription
custom_idstringA unique identifier for this request within the batch.
methodstringThe HTTP method. Always "POST".
urlstringThe API endpoint path.
bodyobjectThe request body, matching the schema for the specified endpoint.

Response Body

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-input123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1709123456,
  "in_progress_at": null,
  "expires_at": 1709209856,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "request_counts": {
    "total": 100,
    "completed": 0,
    "failed": 0
  },
  "metadata": {}
}

Get Batch

Retrieve the status and details of a specific batch.

Request

GET /v1/batches/{batch_id}
ParameterTypeRequiredDescription
batch_idstringYesThe ID of the batch to retrieve (path parameter).

Response Body

Returns a batch object with the same schema as the create response. The status field indicates the current state of the batch.

StatusDescription
validatingThe input file is being validated.
in_progressThe batch is currently being processed.
finalizingThe batch has finished processing and results are being prepared.
completedThe batch is complete. Results are available in output_file_id.
failedThe batch failed. Check errors and error_file_id for details.
expiredThe batch was not completed within the completion window.
cancelledThe batch was cancelled.

List Batches

Retrieve a list of all batches.

Request

GET /v1/batches
ParameterTypeRequiredDescription
limitintegerNoMaximum number of batches to return. Default: 20, max: 100.
afterstringNoA cursor for pagination. Returns batches created after this batch ID.

Response Body

{
  "object": "list",
  "data": [
    {
      "id": "batch_abc123",
      "object": "batch",
      "endpoint": "/v1/chat/completions",
      "status": "completed",
      "input_file_id": "file-input123",
      "output_file_id": "file-output456",
      "created_at": 1709123456,
      "completed_at": 1709145056,
      "request_counts": {
        "total": 100,
        "completed": 98,
        "failed": 2
      },
      "metadata": {}
    }
  ],
  "has_more": false
}

Output File Format

When a batch completes, the results are written to an output file. Each line is a JSON object:

{"id": "batch_req_abc123", "custom_id": "request-1", "response": {"status_code": 200, "request_id": "req_123", "body": {"id": "chatcmpl-abc", "object": "chat.completion", "choices": [{"index": 0, "message": {"role": "assistant", "content": "..."}, "finish_reason": "stop"}], "usage": {"prompt_tokens": 25, "completion_tokens": 100, "total_tokens": 125}}}, "error": null}

Examples

Create a Batch

curl

# Step 1: Upload the input file
curl https://api.tensoras.ai/v1/files \
  -H "Authorization: Bearer tns_your_key_here" \
  -F "file=@batch_input.jsonl" \
  -F "purpose=batch"
 
# Step 2: Create the batch
curl https://api.tensoras.ai/v1/batches \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tns_your_key_here" \
  -d '{
    "input_file_id": "file-input123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h"
  }'

Python

from openai import OpenAI
 
client = OpenAI(
    base_url="https://api.tensoras.ai/v1",
    api_key="tns_your_key_here",
)
 
# Step 1: Upload the input file
input_file = client.files.create(
    file=open("batch_input.jsonl", "rb"),
    purpose="batch",
)
 
# Step 2: Create the batch
batch = client.batches.create(
    input_file_id=input_file.id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
)
 
print(f"Batch ID: {batch.id}")
print(f"Status: {batch.status}")

Node.js

import OpenAI from "openai";
import fs from "fs";
 
const client = new OpenAI({
  baseURL: "https://api.tensoras.ai/v1",
  apiKey: "tns_your_key_here",
});
 
// Step 1: Upload the input file
const inputFile = await client.files.create({
  file: fs.createReadStream("batch_input.jsonl"),
  purpose: "batch",
});
 
// Step 2: Create the batch
const batch = await client.batches.create({
  input_file_id: inputFile.id,
  endpoint: "/v1/chat/completions",
  completion_window: "24h",
});
 
console.log(`Batch ID: ${batch.id}`);
console.log(`Status: ${batch.status}`);

Check Batch Status

curl

curl https://api.tensoras.ai/v1/batches/batch_abc123 \
  -H "Authorization: Bearer tns_your_key_here"

Python

from openai import OpenAI
 
client = OpenAI(
    base_url="https://api.tensoras.ai/v1",
    api_key="tns_your_key_here",
)
 
batch = client.batches.retrieve("batch_abc123")
 
print(f"Status: {batch.status}")
print(f"Progress: {batch.request_counts.completed}/{batch.request_counts.total}")
 
if batch.status == "completed":
    print(f"Output file: {batch.output_file_id}")

Node.js

import OpenAI from "openai";
 
const client = new OpenAI({
  baseURL: "https://api.tensoras.ai/v1",
  apiKey: "tns_your_key_here",
});
 
const batch = await client.batches.retrieve("batch_abc123");
 
console.log(`Status: ${batch.status}`);
console.log(`Progress: ${batch.request_counts.completed}/${batch.request_counts.total}`);
 
if (batch.status === "completed") {
  console.log(`Output file: ${batch.output_file_id}`);
}

List All Batches

curl

curl https://api.tensoras.ai/v1/batches \
  -H "Authorization: Bearer tns_your_key_here"

Python

from openai import OpenAI
 
client = OpenAI(
    base_url="https://api.tensoras.ai/v1",
    api_key="tns_your_key_here",
)
 
batches = client.batches.list(limit=10)
 
for b in batches.data:
    print(f"{b.id}: {b.status} ({b.request_counts.completed}/{b.request_counts.total})")

Node.js

import OpenAI from "openai";
 
const client = new OpenAI({
  baseURL: "https://api.tensoras.ai/v1",
  apiKey: "tns_your_key_here",
});
 
const batches = await client.batches.list({ limit: 10 });
 
for (const b of batches.data) {
  console.log(`${b.id}: ${b.status} (${b.request_counts.completed}/${b.request_counts.total})`);
}

Error Handling

{
  "error": {
    "message": "Batch 'batch_abc123' not found",
    "type": "not_found_error",
    "param": "batch_id",
    "code": "batch_not_found"
  }
}
FilesKnowledge Bases