Skip to main content
POST
https://api.cerebras.ai
/
v1
/
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_456",
    endpoint="/v1/chat/completions",
    completion_window="24h",
    metadata={
        "custom_tags": ["legal-review", "q3"]
    }
)

print(batch)

{
  "id": "batch_5842ec7d8fb6",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file_456",
  "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

​
input_file_id
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
​
endpoint
string
required
The API endpoint for batch processing. Currently only /v1/chat/completions is supported.
​
completion_window
string
required
The time window for batch completion. Currently, only 24h is supported.
​
metadata
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

​
id
string
A unique identifier for the batch job.
​
object
string
The object type, which is always batch.
​
endpoint
string
The API endpoint used for batch processing.
​
errors
object | null
Information about any errors that occurred during batch processing.
​
input_file_id
string
The ID of the input file containing batch requests.
​
completion_window
string
The time window for batch completion. Always 24h.
​
status
string
The current status of the batch job. Possible values: queued, in_progress, finalizing, completed, expired, failed, cancelled, cancelling.
​
output_file_id
string | null
The ID of the file containing batch results (available once processing is complete).
​
error_file_id
string | null
The ID of the file containing errors (if any errors occurred).
​
created_at
integer
The Unix timestamp (in seconds) of when the batch job was created.
​
in_progress_at
integer | null
The Unix timestamp (in seconds) of when the batch job started processing.
​
expires_at
integer | null
The Unix timestamp (in seconds) of when the batch job will expire.
​
finalizing_at
integer | null
The Unix timestamp (in seconds) of when the batch job started finalizing.
​
completed_at
integer | null
The Unix timestamp (in seconds) of when the batch job completed.
​
failed_at
integer | null
The Unix timestamp (in seconds) of when the batch job failed.
​
expired_at
integer | null
The Unix timestamp (in seconds) of when the batch job expired.
​
cancelling_at
integer | null
The Unix timestamp (in seconds) of when the batch job started cancelling.
​
cancelled_at
integer | null
The Unix timestamp (in seconds) of when the batch job was cancelled.
​
request_counts
object
Statistics about the requests in the batch.
​
metadata
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_456",
    endpoint="/v1/chat/completions",
    completion_window="24h",
    metadata={
        "custom_tags": ["legal-review", "q3"]
    }
)

print(batch)

{
  "id": "batch_5842ec7d8fb6",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file_456",
  "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
}