> ## Documentation Index
> Fetch the complete documentation index at: https://inference-docs.cerebras.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve batch

<Callout icon="lock" color="#b2b1b1ff" iconType="regular">
  This feature is in [Private Preview](/support/preview-releases). For access or more information, [contact us](https://www.cerebras.ai/contact) or reach out to your account representative.
</Callout>

Retrieves the status and progress of a batch job. Use this endpoint to monitor your batch job as it processes.

## Path Parameters

<ParamField path="batch_id" type="string" required="true">
  The ID of the batch job to retrieve.
</ParamField>

## Response

<ResponseField name="id" type="string">
  A unique identifier for the batch job.
</ResponseField>

<ResponseField name="object" type="string">
  The object type, which is always `batch`.
</ResponseField>

<ResponseField name="endpoint" type="string">
  The API endpoint used for batch processing.
</ResponseField>

<ResponseField name="errors" type="object | null">
  Information about any errors that occurred during batch processing.
</ResponseField>

<ResponseField name="input_file_id" type="string">
  The ID of the input file containing batch requests.
</ResponseField>

<ResponseField name="completion_window" type="string">
  The time window for batch completion. Always `24h`.
</ResponseField>

<ResponseField name="status" type="string">
  The current status of the batch job. Possible values: `validating`, `queued`, `in_progress`, `finalizing`, `completed`, `expired`, `failed`, `cancelled`, `cancelling`.
</ResponseField>

<ResponseField name="output_file_id" type="string | null">
  The ID of the file containing batch results (available once processing is complete).
</ResponseField>

<ResponseField name="error_file_id" type="string | null">
  The ID of the file containing errors (if any errors occurred).
</ResponseField>

<ResponseField name="created_at" type="integer">
  The Unix timestamp (in seconds) of when the batch job was created.
</ResponseField>

<ResponseField name="in_progress_at" type="integer | null">
  The Unix timestamp (in seconds) of when the batch job started processing.
</ResponseField>

<ResponseField name="expires_at" type="integer | null">
  The Unix timestamp (in seconds) of when the batch job will expire.
</ResponseField>

<ResponseField name="finalizing_at" type="integer | null">
  The Unix timestamp (in seconds) of when the batch job started finalizing.
</ResponseField>

<ResponseField name="completed_at" type="integer | null">
  The Unix timestamp (in seconds) of when the batch job completed.
</ResponseField>

<ResponseField name="failed_at" type="integer | null">
  The Unix timestamp (in seconds) of when the batch job failed.
</ResponseField>

<ResponseField name="expired_at" type="integer | null">
  The Unix timestamp (in seconds) of when the batch job expired.
</ResponseField>

<ResponseField name="cancelling_at" type="integer | null">
  The Unix timestamp (in seconds) of when the batch job started cancelling.
</ResponseField>

<ResponseField name="cancelled_at" type="integer | null">
  The Unix timestamp (in seconds) of when the batch job was cancelled.
</ResponseField>

<ResponseField name="request_counts" type="object">
  Statistics about the requests in the batch.

  <Expandable title="request_counts properties">
    <ResponseField name="total" type="integer">
      Total number of requests in the batch.
    </ResponseField>

    <ResponseField name="completed" type="integer">
      Number of requests that completed successfully.
    </ResponseField>

    <ResponseField name="failed" type="integer">
      Number of requests that failed.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object | null">
  Custom metadata associated with the batch job.
</ResponseField>

<RequestExample>
  ```python Python theme={null}
  from cerebras.cloud.sdk import Cerebras
  import os

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

  batch = client.batches.retrieve("batch_abc123")

  print(batch)
  ```

  ```javascript Node.js theme={null}
  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.retrieve("batch_abc123");

    console.log(batch);
  }

  main();
  ```

  ```bash cURL theme={null}
  curl --location 'https://api.cerebras.ai/v1/batches/batch_abc123' \
  --header "Authorization: Bearer ${CEREBRAS_API_KEY}"
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "batch_abc123",
    "object": "batch",
    "endpoint": "/v1/chat/completions",
    "errors": null,
    "input_file_id": "file_abc123",
    "completion_window": "24h",
    "status": "in_progress",
    "output_file_id": null,
    "error_file_id": null,
    "created_at": 1766003277,
    "in_progress_at": 1766003300,
    "expires_at": 1766089677,
    "finalizing_at": null,
    "completed_at": null,
    "failed_at": null,
    "expired_at": null,
    "cancelling_at": null,
    "cancelled_at": null,
    "request_counts": {
      "total": 100,
      "completed": 75,
      "failed": 2
    },
    "metadata": {
      "custom_tags": ["legal-review", "q3"]
    }
  }
  ```
</ResponseExample>