YouTube Downloader & Scraper

YouTube video file links, transcripts and conversion of video and audio formats.

Pick an action and fill in its fields — the Actor stores the answer in the dataset. Without action it runs getLinks: pass a link and get file links.

Input

action defaults to getLinks (also when it is empty) and selects what to fetch.

Each action uses only its own fields: fields of other actions are ignored and not sent. A key that is not a field of this Actor (e.g. a typo) fails the run. Required fields are checked before any request; an empty or whitespace-only string counts as a missing value.

Action	What it returns	Required	Optional
getLinks	Get file URLs	url	—
transcript	Transcript	videoId	lang
convert	Start conversion	startPayload	—
status	Conversion status	taskId	—

Field	Type	Description
taskId	string, must be letters, digits, _ and - only	Task ID returned by convert.
url	string	A YouTube video link.
videoId	string, must be 11 letters, digits, _ or -	The v= part of the video link.
lang	string	Transcript language code, e.g. en.
startPayload	string	convert: a startPayload value from a getLinks item (a quality that needs conversion).

Example:

{"action":"getLinks","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}

Output

getLinks

One dataset item per resource found at the link (usually one; a post with several media can give several):

{
  "urls": [
    { "url": "https://...", "name": "MP4", "subName": "720", "type": "mp4", "extension": "mp4", "quality": "720p" }
  ],
  "meta": { "title": "...", "sourceUrl": "https://...", "duration": "1:02" },
  "pictureUrl": "https://...",
  "service": "..."
}

• urls — available files; fields such as filesize, audio, quality are present when the service provides them.
• A business error (no downloadable files, private or missing page) is stored as one dataset item as-is and the run still succeeds. It has one of two forms: { "response": 4, "response_type": "link not found", "success": false, "message": "..." } or { "info": "...", "code": ... }.
• A link that is not a YouTube link fails the run before any request is made.
• Direct CDN links can be bound to the IP address of the Actor run and may return 403 when opened from another machine: the Actor does not pass your IP address to the service. Download such links soon after the run, from the same environment if possible.
• A conversion job comes as startPayload instead of url: run convert with this startPayload (see Notes).

API actions

Action	Example input	Key in the item
transcript	{"action":"transcript","videoId":"dQw4w9WgXcQ"}	segments

• Success: the result object of the answer as one dataset item, as is; lists inside it are not split into items.
• A business error ({ "success": false, ... }, e.g. a missing user or video, or { "info": "...", "code": ... }) is stored as one item as-is and the run still succeeds.

convert, status

• convert (startPayload of a conversion job from getLinks): the converter's answer as one item, e.g. { "taskId": "..." }.
• status: the converter's answer as one item (status, progress, downloadUrl when ready, and other fields as is). A failed or unknown task gives one item { "error": "..." } and the run still succeeds.
• downloadUrl is a direct link to the converted file: download it yourself.

Errors

• The run fails without storing data when the input is invalid (checked before any request), the request is rejected or gets an unexpected answer, or the service is still unavailable (an error or no answer within 30 seconds) after retries — about 90 seconds in the worst case.
• Conversion actions fail the run when the converter answers with an unexpected HTTP status or not with a JSON object, or does not answer within 30 seconds.

Pricing

This Actor uses pay-per-event pricing: you pay for the Actor start and for each result, platform usage (compute) is included. The prices are on the Actor's page in Apify Store.

A result is one dataset item with data:

• getLinks: each resource;
• API actions: the result item;
• convert: the taskId item.

Only the Actor start is charged for:

• a business error item;
• status;
• an answer with no items;
• a run that fails.

Notes

• Higher qualities in a getLinks item are conversion jobs, not files: they come with startPayload instead of url. Run convert with this startPayload to get a taskId, then status with the taskId until downloadUrl appears, and download the file from downloadUrl.

Run via API

curl -X POST \
  "https://api.apify.com/v2/acts/logical_variety~youtube/run-sync-get-dataset-items?token=<APIFY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"action":"getLinks","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'