A batch of 50 videos rarely comes back 50 for 50 — a couple of videos might have no captions, one might hit a rate limit, another might just need a second attempt. Scriptube lets you retry only the items that failed, instead of resubmitting (and re-paying for) the whole batch.
This matters most once batches get large enough that manually re-pasting the handful of failed URLs stops being practical — a 300-video channel batch with a dozen failures is faster to clean up with a single retry call than by picking out individual links by hand.
Two kinds of failure
Before retrying, it helps to know why an item failed:
- Permanent failures won't change no matter how many times you retry: no captions available, captions disabled by the uploader, the video is unavailable, or it's members-only content. See why some YouTube videos have no transcript for the full reference list.
- Temporary failures are recoverable: a rate limit, a network blip, a proxy timeout. Retrying these is usually all it takes.
Scriptube's retry endpoint is built around that distinction — by default it only retries what's worth retrying.
Retrying all failed items in a batch
The main endpoint retries every failed item in a batch, or a specific subset:
POST /api/v1/transcripts/{batch_id}/retry-failed
{
"item_ids": ["item_123", "item_456"],
"language": "en",
"translate_to_english": false,
"include_permanent": false,
"force_elevenlabs": false
}
It returns which items were retried and which were skipped:
{
"retried": ["item_123"],
"skipped": ["item_456"]
}
What each option does:
item_ids— optional. Omit it to retry every failed item in the batch; include it to retry only specific ones.language/translate_to_english— optional overrides, in case you want to retry with different language settings than the original submission.include_permanent— by default, items that failed for a permanent reason (no captions, disabled, unavailable) are skipped on retry, since nothing changed. Set this totrueto force a retry anyway — useful if you suspect the situation changed, for example a creator added captions after your first attempt.force_elevenlabs— intended to force an AI transcription fallback for videos with no captions. AI transcription (ElevenLabs) is coming soon and not available yet, so this flag won't produce a transcript for caption-less videos today.
Retrying a single item
If you only want to retry one item rather than passing item_ids to the batch-level call, there's a direct endpoint:
curl -X POST https://scriptube.me/api/v1/transcripts/{batch_id}/items/{item_id}/retry \
-H "X-API-Key: YOUR_API_KEY"
Other batch controls
A few related endpoints cover the rest of a batch's lifecycle:
| Action | Endpoint |
|---|---|
| Retry all failed items | POST /api/v1/transcripts/{batch_id}/retry-failed |
| Retry one item | POST /api/v1/transcripts/{batch_id}/items/{item_id}/retry |
| Rerun the whole batch | POST /api/v1/transcripts/{batch_id}/rerun |
| Cancel a running batch | POST /api/v1/transcripts/{batch_id}/cancel |
| Delete a batch | DELETE /api/v1/transcripts/{batch_id} |
Check before you retry
Rather than retrying blindly, pull the batch's current state first to see exactly which items failed and why:
curl "https://scriptube.me/api/v1/transcripts/{batch_id}?skip=0&limit=50" \
-H "X-API-Key: YOUR_API_KEY"
That response (paginated at up to 50 items per page) tells you which items are worth retrying and which aren't going to change — rather than calling retry-failed on a large batch and hoping it sorts itself out.
Why retry instead of resubmitting
Resubmitting the original URLs as a brand-new batch would re-charge a credit for every video, including the ones that already succeeded the first time. Retry endpoints target only the items that failed, so you're not paying again for what already worked.
A worked example
Submit a 20-video playlist. Two videos come back failed because captions are disabled, and one fails because of a temporary rate limit. Calling retry-failed with default options retries just the rate-limited item — the two caption-disabled items are skipped, since nothing about them has changed:
curl -X POST https://scriptube.me/api/v1/transcripts/batch_abc123/retry-failed \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
If you later learn the uploader turned captions back on for those two videos, retry them explicitly with include_permanent:
curl -X POST https://scriptube.me/api/v1/transcripts/batch_abc123/retry-failed \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"include_permanent": true}'
Handling errors on retry
Errors come back as {code, message, detail}. The ones most relevant to retries:
- 402 — insufficient credits. A retry still consumes a credit per item, same as the original submission.
- 429 — rate limited, with a
Retry-Afterheader telling you how long to wait. - 409
elevenlabs_disabled— returned if you setforce_elevenlabswhile that feature isn't enabled for your account.
How to do it in Scriptube
From the dashboard, open a completed batch, find the failed items listed on the batch detail page, and retry them individually or all at once with a button — no need to resubmit the original URLs. For automated workflows, call retry-failed on a schedule or after a webhook tells you a batch finished with failures (the batch.failed and item.failed events cover this — see webhooks vs. polling).
Related reading
For the full list of reasons an item can fail in the first place, see why some YouTube videos have no transcript. If you're retrying programmatically and want to avoid accidentally double-submitting on a flaky connection, using an Idempotency-Key for safe retries covers the related pattern on /resolve.
Cancelling instead of retrying
If a batch is still running and you've decided you don't want it to continue — say, you spotted a mistake in the submitted URLs — POST /api/v1/transcripts/{batch_id}/cancel stops it rather than letting it finish and then retrying individual items. This is a different action from retry: cancel stops a batch in progress, retry re-attempts items that already finished and failed.
Full endpoint reference is in the API docs. Sign up to get an API key and try it on a real batch.