[{"data":1,"prerenderedAt":16},["ShallowReactive",2],{"blog-batch-process-youtube-playlists-and-channels-at-scale":3},{"slug":4,"title":5,"description":6,"author":7,"tags":8,"content_md":14,"published_at":15,"updated_at":15},"batch-process-youtube-playlists-and-channels-at-scale","Batch Process YouTube Playlists and Channels at Scale with API","Process entire YouTube playlists and channels in a single API call. Learn batch submission patterns, error handling, and scaling strategies for high-volume workflows.","YT2Text Team",[9,10,11,12,13],"batch-processing","api","scale","playlists","automation","If you are building a content pipeline that ingests YouTube videos -- whether for research databases, training data curation, competitive intelligence, or automated publishing -- you will eventually hit the point where processing videos one at a time is no longer practical. This guide walks through the YT2Text Batch API: how it works, how to structure requests, how to handle failures gracefully, and how to get the most out of your plan quota.\n\n## When does single-video processing become a bottleneck?\n\nThe single-video endpoint (`POST /api/v1/videos/process`) works well for on-demand use cases: a user pastes a link, your backend kicks off a job, and results come back in seconds. The friction starts when the number of videos climbs.\n\nConsider a team monitoring 20 YouTube channels, each publishing 3-5 videos per week. That is 60-100 new videos weekly. Submitting them one at a time means 60-100 individual HTTP requests, 60-100 polling loops, and custom code to correlate results back to channels. Network hiccups, transient failures, and rate limits compound quickly.\n\nAccording to MuleSoft's Connectivity Report, API-first architectures reduce integration time by an average of 50% compared to manual workflows. Batch endpoints are a direct expression of this principle: instead of orchestrating dozens of sequential calls, you describe the entire workload in a single request and let the server handle scheduling, retries, and aggregation.\n\nThe crossover point varies by team, but a reliable heuristic is this: if you find yourself writing a loop around the [single-video endpoint](/api/videos), it is time to switch to batch.\n\n## How does the Batch API differ from sequential single-video requests?\n\nThe [Batch API](/api/batch) accepts an array of job definitions in one `POST` request and returns a single `batch_id`. From there, you poll one status endpoint rather than many, and you retrieve consolidated results -- including per-job error details -- from one results endpoint.\n\nKey differences from sequential processing:\n\n- **Single network round-trip for submission.** You send all jobs at once to `POST /api/v1/batch/process`, eliminating the overhead of repeated connections.\n- **Server-side scheduling.** The backend distributes jobs across workers, manages concurrency, and handles internal retries without your intervention.\n- **Unified status tracking.** `GET /api/v1/batch/status/{batch_id}` gives you aggregate progress. No need to maintain a local mapping of job IDs to poll individually.\n- **Structured failure reporting.** The results endpoint separates `successful_jobs` from `failed_jobs` with error codes, so your pipeline can react programmatically to partial failures.\n- **Batch-level webhook support.** The current batch request accepts a single `webhook_url` for the batch submission. See the [webhooks documentation](/api/webhooks) for current payload behavior.\n\nBatch processing is available on the Pro plan ($29/month, 1,000 videos/month). For endpoint details, see the [Batch API reference](/api/batch).\n\n## How do you structure a batch request with mixed summary modes?\n\nA common pattern is processing a playlist where different videos need different treatment -- quick summaries for short clips, detailed breakdowns for long-form content, and timestamped outlines for tutorials. The Batch API supports mixed `summary_modes` values within a single request by letting each video carry its own `options` object.\n\nHere is a curl example that submits five videos with varying modes:\n\n```bash\ncurl -X POST \"https://api.yt2text.cc/api/v1/batch/process\" \\\n  -H \"X-API-Key: sk_your_api_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"videos\": [\n      {\n        \"url\": \"https://www.youtube.com/watch?v=VIDEO_ID_1\",\n        \"options\": {\n          \"summary_modes\": [\"tldr\"]\n        }\n      },\n      {\n        \"url\": \"https://www.youtube.com/watch?v=VIDEO_ID_2\",\n        \"options\": {\n          \"summary_modes\": [\"detailed\"]\n        }\n      },\n      {\n        \"url\": \"https://www.youtube.com/watch?v=VIDEO_ID_3\",\n        \"options\": {\n          \"summary_modes\": [\"study_notes\"]\n        }\n      },\n      {\n        \"url\": \"https://www.youtube.com/watch?v=VIDEO_ID_4\",\n        \"options\": {\n          \"summary_modes\": [\"timestamped\"]\n        }\n      },\n      {\n        \"url\": \"https://www.youtube.com/watch?v=VIDEO_ID_5\",\n        \"options\": {\n          \"summary_modes\": [\"key_insights\"]\n        }\n      }\n    ],\n    \"webhook_url\": \"https://your-app.com/hooks/yt2text\"\n  }'\n```\n\nThe response returns a `batch_id` that you use for all subsequent status and result queries. Each video can request different summary modes through its own `options` object. The current batch schema does not support per-video `custom_instructions`. For API workflow guidance, see [YouTube Transcript API for Developers and Agents](/blog/youtube-transcript-api-for-developers-and-agents).\n\n## How should you handle partial failures in batch results?\n\nNot every video in a batch will succeed. Some videos have disabled transcripts, some are region-locked, and some may be removed between the time you queued the job and the time the worker picked it up. The Batch API reports these cases explicitly through the `partial_failure` status.\n\nWhen you call `GET /api/v1/batch/results/{batch_id}`, the response includes a `status` field that can be `completed`, `processing`, `failed`, or `partial_failure`. The `summary_stats` object tells you exactly how many jobs succeeded and how many did not. Each entry in `failed_jobs` includes an error code and message, which you can map against the [error reference](/reference/errors) for programmatic handling.\n\nRobust pipelines should treat `partial_failure` as an expected outcome, not an exception. Design your downstream logic to process successful results immediately while routing failed job metadata to a retry queue or alerting system. Avoid blocking the entire pipeline on a handful of failures -- the successful results are still valid and available.\n\nThe Python example in the next section demonstrates this pattern end to end.\n\n## What monitoring and alerting should batch pipelines include?\n\nProduction batch pipelines benefit from three layers of observability:\n\n**Submission tracking.** Log every `batch_id` with its submission timestamp, job count, and the source playlist or channel it was derived from. This gives you traceability when debugging weeks later.\n\n**Completion monitoring.** Poll `GET /api/v1/batch/status/{batch_id}` at reasonable intervals (every 10-30 seconds, depending on batch size). Track how long batches take to complete relative to their size. If a batch of 20 videos routinely finishes in 3 minutes but suddenly takes 15, that is worth investigating.\n\n**Failure alerting.** Set thresholds on the failure rate per batch. A batch where 1 out of 50 jobs fails is normal. A batch where 40 out of 50 fail likely indicates a systemic issue -- an expired API key, a quota breach, or an upstream YouTube outage. Pipe these alerts to your team's notification channel.\n\nFor rate limit details and quota management, consult the [rate limits reference](/reference/rate-limits).\n\n## How do you optimize batch throughput within plan quotas?\n\nThe Pro plan provides 1,000 videos per month. Organizations that automate content processing report 3-5x increases in content output without proportional staffing increases, according to the Content Marketing Institute. But to achieve that leverage, you need to spend your quota deliberately.\n\nHere is a Python script that takes a list of video URLs, chunks them into batches, submits each batch, polls for completion, and aggregates results with proper error handling:\n\n```python\nimport time\nimport requests\n\nAPI_BASE = \"https://api.yt2text.cc/api/v1\"\nHEADERS = {\n    \"X-API-Key\": \"sk_your_api_key\",\n    \"Content-Type\": \"application/json\",\n}\nBATCH_SIZE = 25\nPOLL_INTERVAL = 15  # seconds\n\n\ndef chunk_urls(urls, size):\n    for i in range(0, len(urls), size):\n        yield urls[i : i + size]\n\n\ndef submit_batch(video_urls, summary_mode=\"tldr\"):\n    videos = [\n        {\"url\": url, \"options\": {\"summary_modes\": [summary_mode]}}\n        for url in video_urls\n    ]\n    resp = requests.post(\n        f\"{API_BASE}/batch/process\",\n        headers=HEADERS,\n        json={\"videos\": videos},\n    )\n    resp.raise_for_status()\n    return resp.json()[\"data\"][\"batch_id\"]\n\n\ndef poll_until_done(batch_id):\n    while True:\n        resp = requests.get(\n            f\"{API_BASE}/batch/status/{batch_id}\",\n            headers=HEADERS,\n        )\n        resp.raise_for_status()\n        status = resp.json()[\"data\"][\"status\"]\n        if status in (\"completed\", \"failed\", \"partial_failure\"):\n            return status\n        time.sleep(POLL_INTERVAL)\n\n\ndef fetch_results(batch_id):\n    resp = requests.get(\n        f\"{API_BASE}/batch/results/{batch_id}\",\n        headers=HEADERS,\n    )\n    resp.raise_for_status()\n    return resp.json()[\"data\"]\n\n\ndef process_all(video_urls, summary_mode=\"tldr\"):\n    all_successful = []\n    all_failed = []\n\n    for i, chunk in enumerate(chunk_urls(video_urls, BATCH_SIZE)):\n        print(f\"Submitting batch {i + 1} ({len(chunk)} videos)...\")\n        batch_id = submit_batch(chunk, summary_mode)\n\n        status = poll_until_done(batch_id)\n        results = fetch_results(batch_id)\n\n        all_successful.extend(results.get(\"successful_jobs\", []))\n        all_failed.extend(results.get(\"failed_jobs\", []))\n\n        stats = results.get(\"summary_stats\", {})\n        print(\n            f\"  Batch {i + 1}: {stats.get('successful', 0)} succeeded, \"\n            f\"{stats.get('failed', 0)} failed (status: {status})\"\n        )\n\n    print(f\"\\nTotal: {len(all_successful)} succeeded, {len(all_failed)} failed\")\n\n    if all_failed:\n        print(\"\\nFailed jobs:\")\n        for job in all_failed:\n            error = job.get(\"error\", {})\n            print(f\"  - {job['job_id']}: {error.get('code')} - {error.get('message')}\")\n\n    return all_successful, all_failed\n\n\n# Usage\nvideo_urls = [\n    \"https://www.youtube.com/watch?v=VIDEO_ID_1\",\n    \"https://www.youtube.com/watch?v=VIDEO_ID_2\",\n    # ... up to 1,000 per month on Pro plan\n]\n\nsuccessful, failed = process_all(video_urls, summary_mode=\"detailed\")\n```\n\nA few optimization strategies to keep in mind:\n\n- **Deduplicate before submitting.** If the same video appears in multiple playlists, process it once and reference the cached result.\n- **Choose the right summary mode.** `tldr` is faster and cheaper on LLM tokens than `detailed`. Use lighter modes for triage and reserve heavier modes for videos you have already identified as high-value.\n- **Stagger submissions.** If you are processing close to your monthly quota, spread batches across the month rather than burning through 200 videos on day one. This also smooths your rate limit usage -- see the [rate limits reference](/reference/rate-limits) for per-minute and per-hour caps.\n- **Use webhooks instead of polling.** Set a batch-level `webhook_url` to receive a push notification on completion. This eliminates polling overhead entirely and is documented in the [webhooks guide](/api/webhooks).\n\n## Key Takeaways\n\n- The single-video endpoint works for on-demand processing, but any workflow involving more than a handful of videos benefits from the Batch API's consolidated submission and result retrieval.\n- Structure batch requests with mixed `summary_modes` values inside each video's `options` object to match each video's content type and your downstream needs.\n- Treat `partial_failure` as a normal operating state. Design pipelines to process successful results immediately and route failures to retry logic or alerting.\n- Monitor batch completion times and failure rates to catch systemic issues early.\n- Optimize quota usage by deduplicating URLs, choosing appropriate summary modes, and leveraging webhooks to eliminate polling.\n- The Batch API is available on the [Pro plan](/reference/rate-limits) at $29/month with a 200 video/month allowance.","2026-03-07T00:00:00.000Z",1776276515900]