Overview
Batch downloads allow you to download all episodes from a Spotify podcast show with a single API call. Tornado automatically extracts all episode URLs and creates individual jobs for each.
Batch downloads are currently supported for Spotify Shows only.
How It Works
Submit Show URL
Send a Spotify show URL to the /jobs endpoint
Episode Extraction
Tornado extracts all episode URLs from the show (can take 30-120 seconds for large shows)
Batch Creation
A batch job is created with individual jobs for each episode
Parallel Processing
Episodes are downloaded in parallel for maximum speed
Progress Tracking
Track overall progress via the batch status endpoint
Create a Batch
curl -X POST "https://tornado.velys.software/jobs" \
-H "x-api-key: sk_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"url": "https://open.spotify.com/show/7iQXmUT7XGuZSzAMjoNWlX",
"folder": "my-podcast-2024",
"webhook_url": "https://myapp.com/batch-complete"
}'
Batch Response
When you submit a Spotify show URL, you receive a batch response instead of a single job:
{
"batch_id": "550e8400-e29b-41d4-a716-446655440001",
"total_episodes": 142,
"episode_jobs": [
"job-uuid-1",
"job-uuid-2",
"job-uuid-3",
"..."
]
}
Check Batch Status
Poll the batch endpoint for progress:
curl -X GET "https://tornado.velys.software/batch/550e8400-e29b-41d4-a716-446655440001"
Response
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"show_url": "https://open.spotify.com/show/7iQXmUT7XGuZSzAMjoNWlX",
"status": "processing",
"folder": "my-podcast-2024",
"total_episodes": 142,
"completed_episodes": 45,
"failed_episodes": 2,
"episode_jobs": ["job-uuid-1", "job-uuid-2", "..."]
}
Batch Status Values
| Status | Description |
|---|
processing | Batch is being processed, some episodes may be complete |
completed | All episodes finished successfully |
finished | All episodes done, but some failed |
Batch Webhook
When a batch completes (all episodes done), a webhook is sent:
{
"type": "batch_completed",
"batch_id": "550e8400-e29b-41d4-a716-446655440001",
"show_url": "https://open.spotify.com/show/...",
"folder": "my-podcast-2024",
"completed": 140,
"failed": 2,
"total": 142
}
The batch webhook fires once when all episodes are done (completed + failed = total), not for each individual episode.
Folder Structure
All episodes are saved with the folder prefix you specify:
my-podcast-2024/
├── Episode 1 - Introduction.mp4
├── Episode 2 - Getting Started.mp4
├── Episode 3 - Deep Dive.mp4
└── ...
Python Example
import requests
import time
API_KEY = "sk_your_api_key"
BASE_URL = "https://tornado.velys.software"
def download_podcast(show_url, folder):
# Create batch
response = requests.post(
f"{BASE_URL}/jobs",
headers={"x-api-key": API_KEY},
json={
"url": show_url,
"folder": folder
}
)
data = response.json()
batch_id = data["batch_id"]
total = data["total_episodes"]
print(f"Batch created: {batch_id}")
print(f"Total episodes: {total}")
# Poll for progress
while True:
status = requests.get(
f"{BASE_URL}/batch/{batch_id}",
headers={"x-api-key": API_KEY}
).json()
completed = status["completed_episodes"]
failed = status["failed_episodes"]
print(f"Progress: {completed}/{total} ({failed} failed)")
if status["status"] in ["completed", "finished"]:
break
time.sleep(10)
print(f"Batch complete! Status: {status['status']}")
# Download a podcast
download_podcast(
"https://open.spotify.com/show/7iQXmUT7XGuZSzAMjoNWlX",
"huberman-lab-2024"
)
| Metric | Value |
|---|
| Max episodes per batch | Unlimited |
| Concurrent downloads | ~100 per batch |
| Typical speed | 10-50 episodes/minute |
| Extraction timeout | 120 seconds |
Very large shows (500+ episodes) may take longer to extract. The extraction process uses Scrapeless for reliable data fetching.
