Create batch

from cerebras.cloud.sdk import Cerebras
import os

client = Cerebras(
    api_key=os.environ.get("CEREBRAS_API_KEY"),
)

batch = client.batches.create(
    input_file_id="file_abc123",
    endpoint="/v1/chat/completions",
    completion_window="24h",
    metadata={
        "custom_tags": ["legal-review", "q3"]
    }
)

print(batch)

import Cerebras from '@cerebras/cerebras_cloud_sdk';

const client = new Cerebras({
  apiKey: process.env['CEREBRAS_API_KEY'],
});

async function main() {
  const batch = await client.batches.create({
    input_file_id: "file_abc123",
    endpoint: "/v1/chat/completions",
    completion_window: "24h",
    metadata: {
      custom_tags: ["legal-review", "q3"]
    }
  });

  console.log(batch);
}

main();

curl --location 'https://api.cerebras.ai/v1/batches' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${CEREBRAS_API_KEY}" \
--data '{
  "input_file_id": "file_abc123",
  "endpoint": "/v1/chat/completions",
  "completion_window": "24h",
  "metadata": {
    "custom_tags": ["legal-review", "q3"]
  }
}'

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file_abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1766003277,
  "in_progress_at": null,
  "expires_at": null,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "metadata": null
}

POST

batches

from cerebras.cloud.sdk import Cerebras
import os

client = Cerebras(
    api_key=os.environ.get("CEREBRAS_API_KEY"),
)

batch = client.batches.create(
    input_file_id="file_abc123",
    endpoint="/v1/chat/completions",
    completion_window="24h",
    metadata={
        "custom_tags": ["legal-review", "q3"]
    }
)

print(batch)

import Cerebras from '@cerebras/cerebras_cloud_sdk';

const client = new Cerebras({
  apiKey: process.env['CEREBRAS_API_KEY'],
});

async function main() {
  const batch = await client.batches.create({
    input_file_id: "file_abc123",
    endpoint: "/v1/chat/completions",
    completion_window: "24h",
    metadata: {
      custom_tags: ["legal-review", "q3"]
    }
  });

  console.log(batch);
}

main();

curl --location 'https://api.cerebras.ai/v1/batches' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${CEREBRAS_API_KEY}" \
--data '{
  "input_file_id": "file_abc123",
  "endpoint": "/v1/chat/completions",
  "completion_window": "24h",
  "metadata": {
    "custom_tags": ["legal-review", "q3"]
  }
}'

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file_abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1766003277,
  "in_progress_at": null,
  "expires_at": null,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "metadata": null
}

This feature is in Private Preview. For access or more information, contact us or reach out to your account representative.

See the Batch guide for more information.

Request

string

required

The ID of an uploaded file that contains requests for the batch job.The file must follow these constraints:

Max size of 200 MB
Uploaded with purpose: "batch"
Max 50,000 requests

string

required

The API endpoint for batch processing. Currently only /v1/chat/completions is supported.

string

required

The time window for batch completion. Currently, only 24h is supported.

object

Key-value pairs that can be attached to an object. Optional custom metadata for the batch job. Useful for organizing and tracking batch jobs.

Response

string

A unique identifier for the batch job.

string

The object type, which is always batch.

string

The API endpoint used for batch processing.

object | null

Information about any errors that occurred during batch processing.

string

The ID of the input file containing batch requests.

string

The time window for batch completion. Always 24h.

string

The current status of the batch job. Possible values: queued, in_progress, finalizing, completed, expired, failed, cancelled, cancelling.

string | null

The ID of the file containing batch results (available once processing is complete).

string | null

The ID of the file containing errors (if any errors occurred).

integer

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

integer | null

The Unix timestamp (in seconds) of when the batch job started processing.

integer | null

The Unix timestamp (in seconds) of when the batch job will expire.

integer | null

The Unix timestamp (in seconds) of when the batch job started finalizing.

integer | null

The Unix timestamp (in seconds) of when the batch job completed.

integer | null

The Unix timestamp (in seconds) of when the batch job failed.

integer | null

The Unix timestamp (in seconds) of when the batch job expired.

integer | null

The Unix timestamp (in seconds) of when the batch job started cancelling.

integer | null

The Unix timestamp (in seconds) of when the batch job 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 | null

Custom metadata associated with the batch job.

from cerebras.cloud.sdk import Cerebras
import os

client = Cerebras(
    api_key=os.environ.get("CEREBRAS_API_KEY"),
)

batch = client.batches.create(
    input_file_id="file_abc123",
    endpoint="/v1/chat/completions",
    completion_window="24h",
    metadata={
        "custom_tags": ["legal-review", "q3"]
    }
)

print(batch)

import Cerebras from '@cerebras/cerebras_cloud_sdk';

const client = new Cerebras({
  apiKey: process.env['CEREBRAS_API_KEY'],
});

async function main() {
  const batch = await client.batches.create({
    input_file_id: "file_abc123",
    endpoint: "/v1/chat/completions",
    completion_window: "24h",
    metadata: {
      custom_tags: ["legal-review", "q3"]
    }
  });

  console.log(batch);
}

main();

curl --location 'https://api.cerebras.ai/v1/batches' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${CEREBRAS_API_KEY}" \
--data '{
  "input_file_id": "file_abc123",
  "endpoint": "/v1/chat/completions",
  "completion_window": "24h",
  "metadata": {
    "custom_tags": ["legal-review", "q3"]
  }
}'

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file_abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1766003277,
  "in_progress_at": null,
  "expires_at": null,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "metadata": null
}

Public models

Retrieve batch

⌘I

Introduction

Chat

Completions

Models

Batch

Files

Metrics

Management

Request

Response

​Request

​Response

Request

Response