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

# Get Batch Status

> Get the status of a Spotify show batch download

## Overview

Retrieves the current status and progress of a batch download operation.

## Header Parameters

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication
</ParamField>

## Path Parameters

<ParamField path="id" type="string" required>
  The batch UUID returned from `POST /jobs` when submitting a Spotify show URL
</ParamField>

## Response

<ResponseField name="id" type="string">
  Batch UUID
</ResponseField>

<ResponseField name="show_url" type="string">
  Original Spotify show URL
</ResponseField>

<ResponseField name="status" type="string">
  Batch status: `paused`, `processing`, `completed`, or `finished`
</ResponseField>

<ResponseField name="folder" type="string">
  S3 folder prefix for episodes
</ResponseField>

<ResponseField name="total_episodes" type="integer">
  Total number of episodes in the show
</ResponseField>

<ResponseField name="completed_episodes" type="integer">
  Number of successfully completed episodes
</ResponseField>

<ResponseField name="failed_episodes" type="integer">
  Number of failed episodes
</ResponseField>

<ResponseField name="skipped_episodes" type="integer">
  Number of skipped episodes (e.g. audio-only Spotify episodes protected by Widevine DRM)
</ResponseField>

<ResponseField name="episode_jobs" type="array">
  List of individual job UUIDs for each episode
</ResponseField>

## Example

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://api.tornadoapi.io/batch/550e8400-e29b-41d4-a716-446655440001" \
    -H "x-api-key: sk_your_api_key"
  ```

  ```json Processing theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "show_url": "https://open.spotify.com/show/7iQXmUT7XGuZSzAMjoNWlX",
    "status": "processing",
    "folder": "huberman-lab-2024",
    "total_episodes": 142,
    "completed_episodes": 45,
    "failed_episodes": 2,
    "episode_jobs": ["uuid-1", "uuid-2", "uuid-3", "..."]
  }
  ```

  ```json Completed (All Successful) theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "show_url": "https://open.spotify.com/show/7iQXmUT7XGuZSzAMjoNWlX",
    "status": "completed",
    "folder": "huberman-lab-2024",
    "total_episodes": 142,
    "completed_episodes": 142,
    "failed_episodes": 0,
    "episode_jobs": ["uuid-1", "uuid-2", "..."]
  }
  ```

  ```json Finished (With Failures) theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "show_url": "https://open.spotify.com/show/7iQXmUT7XGuZSzAMjoNWlX",
    "status": "finished",
    "folder": "huberman-lab-2024",
    "total_episodes": 142,
    "completed_episodes": 140,
    "failed_episodes": 2,
    "episode_jobs": ["uuid-1", "uuid-2", "..."]
  }
  ```
</CodeGroup>

## Status Values

| Status       | Meaning                                                                 |
| ------------ | ----------------------------------------------------------------------- |
| `paused`     | Batch created with `paused: true`, waiting for `POST /batch/{id}/start` |
| `processing` | Batch is in progress, episodes are being downloaded                     |
| `completed`  | All episodes finished successfully (0 failures)                         |
| `finished`   | All episodes done, but some failed                                      |

## Progress Calculation

```
Progress = (completed_episodes + failed_episodes) / total_episodes * 100
```

A batch is finished when:

```
completed_episodes + failed_episodes >= total_episodes
```

## Polling Example

```python theme={null}
import requests
import time

def wait_for_batch(batch_id, api_key):
    while True:
        response = requests.get(
            f"https://api.tornadoapi.io/batch/{batch_id}",
            headers={"x-api-key": api_key}
        )
        data = response.json()

        completed = data["completed_episodes"]
        failed = data["failed_episodes"]
        total = data["total_episodes"]

        print(f"Progress: {completed + failed}/{total} ({failed} failed)")

        if data["status"] in ["completed", "finished"]:
            return data

        time.sleep(10)

# Usage
result = wait_for_batch("batch-uuid", "sk_your_api_key")
print(f"Final status: {result['status']}")
```

## Success Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "show_url": "https://open.spotify.com/show/7iQXmUT7XGuZSzAMjoNWlX",
    "status": "completed",
    "folder": "huberman-lab-2024",
    "total_episodes": 142,
    "completed_episodes": 142,
    "failed_episodes": 0,
    "skipped_episodes": 0,
    "episode_jobs": ["uuid-1", "uuid-2", "uuid-3"]
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 404 Not Found theme={null}
  null
  ```
</ResponseExample>

## Checking Individual Episodes

To see details about failed episodes, query individual job IDs:

```bash theme={null}
curl -X GET "https://api.tornadoapi.io/jobs/{episode_job_id}" \
  -H "x-api-key: sk_your_api_key"
```