Batch Process YouTube Playlists and Channels at Scale with API

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.

When does single-video processing become a bottleneck?

The 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.

Consider 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.

According 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.

The crossover point varies by team, but a reliable heuristic is this: if you find yourself writing a loop around the single-video endpoint, it is time to switch to batch.

How does the Batch API differ from sequential single-video requests?

The Batch API 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.

Key differences from sequential processing:

Single network round-trip for submission. You send all jobs at once to
```
POST /api/v1/batch/process
```
, eliminating the overhead of repeated connections.
Server-side scheduling. The backend distributes jobs across workers, manages concurrency, and handles internal retries without your intervention.
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.
Structured failure reporting. The results endpoint separates
```
successful_jobs
```
from
```
failed_jobs
```
with error codes, so your pipeline can react programmatically to partial failures.
Webhook support per job. Each job in the batch can specify its own
```
webhook_url
```
, allowing fine-grained notification routing. See the webhooks documentation for payload format and retry behavior.

Batch processing is available on the Pro plan ($29/month, 200 videos/month). For endpoint details, see the Batch API reference.

How do you structure a batch request with mixed summary modes?

A 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_mode

values within a single request.

Here is a curl example that submits five videos with varying modes:

curl -X POST "https://api.yt2text.cc/api/v1/batch/process" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jobs": [
      {
        "video_url": "https://www.youtube.com/watch?v=VIDEO_ID_1",
        "summary_mode": "tldr",
        "webhook_url": "https://your-app.com/hooks/yt2text"
      },
      {
        "video_url": "https://www.youtube.com/watch?v=VIDEO_ID_2",
        "summary_mode": "detailed",
        "custom_instructions": "Focus on technical architecture decisions"
      },
      {
        "video_url": "https://www.youtube.com/watch?v=VIDEO_ID_3",
        "summary_mode": "study_notes"
      },
      {
        "video_url": "https://www.youtube.com/watch?v=VIDEO_ID_4",
        "summary_mode": "timestamped"
      },
      {
        "video_url": "https://www.youtube.com/watch?v=VIDEO_ID_5",
        "summary_mode": "key_insights",
        "webhook_url": "https://your-app.com/hooks/yt2text"
      }
    ]
  }'

The response returns a

batch_id

that you use for all subsequent status and result queries. Note that

custom_instructions

is optional and lets you steer the AI summarizer for specific jobs without affecting the rest of the batch. For guidance on normalizing YouTube URLs before submission, see YouTube Transcript API Best Practices.

How should you handle partial failures in batch results?

Not 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.

When 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 for programmatic handling.

Robust 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.

The Python example in the next section demonstrates this pattern end to end.

What monitoring and alerting should batch pipelines include?

Production batch pipelines benefit from three layers of observability:

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.

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.

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.

For rate limit details and quota management, consult the rate limits reference.

How do you optimize batch throughput within plan quotas?

The Pro plan provides 200 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.

Here 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:

import time
import requests

API_BASE = "https://api.yt2text.cc/api/v1"
HEADERS = {
    "X-API-Key": "sk_your_api_key",
    "Content-Type": "application/json",
}
BATCH_SIZE = 25
POLL_INTERVAL = 15  # seconds


def chunk_urls(urls, size):
    for i in range(0, len(urls), size):
        yield urls[i : i + size]


def submit_batch(video_urls, summary_mode="tldr"):
    jobs = [
        {"video_url": url, "summary_mode": summary_mode}
        for url in video_urls
    ]
    resp = requests.post(
        f"{API_BASE}/batch/process",
        headers=HEADERS,
        json={"jobs": jobs},
    )
    resp.raise_for_status()
    return resp.json()["data"]["batch_id"]


def poll_until_done(batch_id):
    while True:
        resp = requests.get(
            f"{API_BASE}/batch/status/{batch_id}",
            headers=HEADERS,
        )
        resp.raise_for_status()
        status = resp.json()["data"]["status"]
        if status in ("completed", "failed", "partial_failure"):
            return status
        time.sleep(POLL_INTERVAL)


def fetch_results(batch_id):
    resp = requests.get(
        f"{API_BASE}/batch/results/{batch_id}",
        headers=HEADERS,
    )
    resp.raise_for_status()
    return resp.json()["data"]


def process_all(video_urls, summary_mode="tldr"):
    all_successful = []
    all_failed = []

    for i, chunk in enumerate(chunk_urls(video_urls, BATCH_SIZE)):
        print(f"Submitting batch {i + 1} ({len(chunk)} videos)...")
        batch_id = submit_batch(chunk, summary_mode)

        status = poll_until_done(batch_id)
        results = fetch_results(batch_id)

        all_successful.extend(results.get("successful_jobs", []))
        all_failed.extend(results.get("failed_jobs", []))

        stats = results.get("summary_stats", {})
        print(
            f"  Batch {i + 1}: {stats.get('successful', 0)} succeeded, "
            f"{stats.get('failed', 0)} failed (status: {status})"
        )

    print(f"\nTotal: {len(all_successful)} succeeded, {len(all_failed)} failed")

    if all_failed:
        print("\nFailed jobs:")
        for job in all_failed:
            error = job.get("error", {})
            print(f"  - {job['job_id']}: {error.get('code')} - {error.get('message')}")

    return all_successful, all_failed


# Usage
video_urls = [
    "https://www.youtube.com/watch?v=VIDEO_ID_1",
    "https://www.youtube.com/watch?v=VIDEO_ID_2",
    # ... up to 200 per month on Pro plan
]

successful, failed = process_all(video_urls, summary_mode="detailed")

A few optimization strategies to keep in mind:

Deduplicate before submitting. If the same video appears in multiple playlists, process it once and reference the cached result.
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.
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 for per-minute and per-hour caps.
Use webhooks instead of polling. For each job, set a
```
webhook_url
```
to receive a push notification on completion. This eliminates polling overhead entirely and is documented in the webhooks guide.

Key Takeaways

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.
Structure batch requests with mixed
```
summary_mode
```
values to match each video's content type and your downstream needs.
Treat
```
partial_failure
```
as a normal operating state. Design pipelines to process successful results immediately and route failures to retry logic or alerting.
Monitor batch completion times and failure rates to catch systemic issues early.
Optimize quota usage by deduplicating URLs, choosing appropriate summary modes, and leveraging webhooks to eliminate polling.
The Batch API is available on the Pro plan at $29/month with a 200 video/month allowance.