catalyst-labs/youtube-transcript-api
catalyst-labs--youtube-transcript-apiDestructive
This tool calls the Actor "catalyst-labs/youtube-transcript-api" and retrieves its output results. Actor description: Starts a YouTube transcript run (videos, playlists, channels, search) and waits up to waitSecs (max 45s). Returns results, or a runId to poll with get-actor-run, then fetch rows with get-dataset-items. Use those for runs already started. $0.008/transcript, less on paid plans; no-caption videos free.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | "transcripts" downloads transcripts. "listCaptionTracks" is free: it returns each video's caption languages and track types (creator or auto-generated) and which track a transcript run would return, without downloading or charging a transcript. Up to 1,000 videos per run. Example: "listCaptionTracks" Example values: "transcripts" | transcripts |
| videos | No | One per line: video, Shorts or youtu.be links, 11-character video IDs, playlist URLs, or channel URLs/@handles (add /shorts or /streams for those tabs). Channels return newest videos first. Example values: ["https://www.youtube.com/watch?v=jNQXAC9IVRw","https://www.youtube.com/@TED"] | |
| waitSecs | No | Max seconds (0–45, default 30) to cap the wait for the Actor run to reach terminal state. For long-running Actors the response returns at the cap with the current run status; follow `nextStep` to poll via get-actor-run. Set to 0 to fire-and-forget. | |
| languages | No | Caption languages in order of preference (ISO codes, e.g. en, es, pt-BR). The first one available is returned. Regional variants count: "en" also matches en-GB and en-US, and a human-made track in any variant is used before an auto-generated one. Example values: ["en"] | |
| maxVideos | No | Overall cap across all sources. 0 = no cap. | |
| monitorId | No | Optional name for the incremental-monitoring memory, e.g. "competitors-tech". Defaults to the list of sources. | |
| punctuate | No | Some YouTube auto-generated captions come as one long lowercase stream with no punctuation. When enabled, those tracks get sentence punctuation (. , ?) and capitalization restored by a built-in model, returned as punctuatedText (and punctuatedSegments). The raw text and segments are never changed. Human-made captions and auto-captions YouTube already punctuated are left as they are. No extra charge. Supported: English and 44 other space-separated languages (not Japanese/Chinese). | |
| maxRetries | No | Retries with backoff (and a fresh proxy session) after rate limits or network errors. Example values: 3 | |
| searchSort | No | How search results are ordered. Example values: "relevance" | relevance |
| captionType | No | Which caption tracks may be used. Every result says whether it is auto-generated. Example values: "any" | any |
| referrer_id | No | Referral code from another user's receipt (ref_...). They earn 10% of this run's price as credit. | |
| translateTo | No | Optional ISO code, best effort. If none of the preferred languages exists, ask YouTube for its machine translation. YouTube often refuses these requests from servers; then the original captions are returned with a warning (or TRANSLATION_UNAVAILABLE if fallback is off). Never charged when it fails. | |
| preferManual | No | When both exist in a language (including regional variants such as en-GB / en-US), use the human-made track. Example values: true | |
| onlyNewVideos | No | Skip videos this monitor already delivered in earlier runs (not charged). Schedule the run daily to track competitor channels. | |
| outputFormats | No | One or more formats per transcript. All formats cost the same. "LLM-ready text" adds llmText: the same words with sound cues ([Music], [Applause], (laughs)), music notes and >> speaker markers removed; the raw text field is unchanged. "Markdown" adds a markdown field per video and one combined TRANSCRIPTS.md file in the key-value store. Example values: ["text","segments"] | |
| searchQueries | No | Optional. Each term is searched on YouTube and its top videos are transcribed (up to "Max videos per source"). | |
| buyerPublicKey | No | Base64 Ed25519 public key (SPKI). Lets you sign a useful/not useful verdict on this run's receipt. Verdicts are recorded but never earn credit or discounts. | |
| includeDetails | No | Adds publishDate, likeCount, commentCount and the channel's subscriberCount (one extra request per video, no extra charge). YouTube rounds comment counts above 1,000 and subscriber counts (e.g. 2.4M), so those are approximate. Turned on automatically when you use a date filter. Example values: true | |
| maxConcurrency | No | Videos fetched in parallel. Example values: 5 | |
| publishedAfter | No | Only videos published on/after this date: YYYY-MM-DD or relative like "30 days". Uses exact upload dates. | |
| includeMetadata | No | Title, channel, duration, views, tags, thumbnail. Example values: true | |
| publishedBefore | No | Only videos published on/before this date: YYYY-MM-DD or relative like "7 days". | |
| disableAutoProxy | No | Only for debugging: never switch to a proxy automatically. | |
| includeDescription | No | Adds the full video description. | |
| maxVideosPerSource | No | Cap per playlist, channel tab or search term (newest first for channels). 0 = all. Single video links are always included. Example values: 5 | |
| proxyConfiguration | No | Leave empty for automatic mode: the Actor starts without a proxy and, if YouTube blocks it, switches to Apify datacenter and then residential proxy at no extra cost to you. Set your own proxy here to override. | |
| fallbackToAnyLanguage | No | If no preferred language (or translation) exists, return the video's original spoken language (human-made track if there is one), or the best available track, instead of failing. The result then has requestedLanguageFound=false, languageFallback ("originalLanguage" or "anyLanguage") and a warning. Example values: true |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tip | No | Advisory guidance RAG Web Browser wrote to its key-value store under the reserved "TIP" key | |
| runId | Yes | Actor run ID | |
| stats | No | Run statistics | |
| status | Yes | Run status: READY | RUNNING | TIMING-OUT | TIMED-OUT | ABORTING | ABORTED | SUCCEEDED | FAILED | |
| actorId | Yes | Stable Apify Actor ID from the run record | |
| summary | Yes | Past-tense summary of the run state | |
| exitCode | No | Actor process exit code; populated for terminal states (especially FAILED) | |
| nextStep | Yes | One primary follow-up action with identifiers interpolated | |
| storages | Yes | Dataset and key-value store metadata, keyed by alias. "default" is always the primary entry. | |
| actorName | No | "username/actor-name" | |
| startedAt | No | ISO timestamp when the run started | |
| finishedAt | No | ISO timestamp when the run finished (terminal states only) | |
| statusMessage | No | Pass-through from Apify run.statusMessage | |
| apifyConsoleUrl | No | Personalized Apify Console link to the run; present only for Console sessions |