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

# Retrieve batch

Retrieve the status and details of a specific batch job. Use this to monitor batch progress and get the output file ID when the batch completes.

<Note>
  **Customer credentials required**: This endpoint requires your own OpenAI API key configured in Keywords AI dashboard (Settings → Providers).
</Note>

## Keywords AI parameters

You can pass Keywords AI tracking parameters via the `X-Data-Keywordsai-Params` header:

```bash theme={"system"}
-H "X-Data-Keywordsai-Params: {\"customer_identifier\": \"user123\"}"
```

## Path parameters

<ParamField path="batch_id" type="string" required>
  The unique identifier of the batch to retrieve. Format: `batch_xxxxx`

  <Accordion title="Example">
    ```
    batch_abc123
    ```
  </Accordion>
</ParamField>

## Response

Returns a batch object with complete status information.

**Key fields:**

* `status` - Current batch status (see [create batch](/api-endpoints/develop/openai-batch/batches/create) for status values)
* `output_file_id` - ID of the output file when batch completes (use with [retrieve file content](/api-endpoints/develop/openai-batch/files/content))
* `error_file_id` - ID of the error file if any requests failed
* `request_counts` - Progress tracking with total, completed, and failed counts

<ResponseExample>
  ```json 200 OK theme={"system"}
  {
    "id": "batch_abc123",
    "object": "batch",
    "endpoint": "/v1/chat/completions",
    "errors": null,
    "input_file_id": "file-abc123",
    "completion_window": "24h",
    "status": "completed",
    "output_file_id": "file-xyz789",
    "error_file_id": null,
    "created_at": 1711471533,
    "in_progress_at": 1711471538,
    "expires_at": 1711557933,
    "finalizing_at": 1711493133,
    "completed_at": 1711493163,
    "failed_at": null,
    "expired_at": null,
    "cancelling_at": null,
    "cancelled_at": null,
    "request_counts": {
      "total": 100,
      "completed": 95,
      "failed": 5
    },
    "metadata": {
      "description": "Customer analysis batch"
    }
  }
  ```

  ```json 404 Not Found theme={"system"}
  {
    "error": {
      "message": "No such batch: batch_abc123",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 401 Unauthorized theme={"system"}
  {
    "error": "Authentication credentials were not provided."
  }
  ```
</ResponseExample>

<RequestExample>
  ```python Python theme={"system"}
  import requests
  import json

  batch_id = "batch_abc123"
  url = f"https://api.keywordsai.co/api/v1/batches/{batch_id}/"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "X-Data-Keywordsai-Params": json.dumps({
          "customer_identifier": "user123"
      })
  }

  response = requests.get(url, headers=headers)
  batch = response.json()

  print(f"Status: {batch['status']}")
  if batch['status'] == 'completed':
      print(f"Output file: {batch['output_file_id']}")
  ```

  ```typescript TypeScript theme={"system"}
  const batchId = 'batch_abc123';
  const url = `https://api.keywordsai.co/api/v1/batches/${batchId}/`;
  const headers = {
      'Authorization': 'Bearer YOUR_API_KEY',
      'X-Data-Keywordsai-Params': JSON.stringify({
          customer_identifier: 'user123'
      })
  };

  const response = await fetch(url, {
      method: 'GET',
      headers: headers
  });

  const data = await response.json();
  console.log(`Status: ${data.status}`);
  ```

  ```bash cURL theme={"system"}
  curl https://api.keywordsai.co/api/v1/batches/batch_abc123/ \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "X-Data-Keywordsai-Params: {\"customer_identifier\": \"user123\"}"
  ```
</RequestExample>