{ "openapi": "3.0.1", "info": { "title": "YouTube Scraper - Videos, Channels & Transcripts", "description": "Search YouTube videos, list channel videos, and collect public channel details, comments, replies, and available transcripts. Pay per delivered row plus a start fee.", "version": "0.8", "x-build-id": "QyA36bfmQZysjNZhy" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/lentic_clockss~youtube-research-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-lentic_clockss-youtube-research-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/lentic_clockss~youtube-research-scraper/runs": { "post": { "operationId": "runs-sync-lentic_clockss-youtube-research-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/lentic_clockss~youtube-research-scraper/run-sync": { "post": { "operationId": "run-sync-lentic_clockss-youtube-research-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "searchQueries": { "title": "Search queries", "maxItems": 50, "uniqueItems": true, "type": "array", "description": "Keywords to search on YouTube. Each distinct query gets its own maxResults row allowance; comma- or newline-separated text is also accepted.", "items": { "minLength": 1, "maxLength": 160, "type": "string" } }, "channelUrls": { "title": "Channel URLs", "maxItems": 50, "uniqueItems": true, "type": "array", "description": "Public channel links, @handles, or channel IDs starting with UC. Each distinct input has one maxResults allowance shared by all selected tabs and any extra rows.", "items": { "minLength": 2, "maxLength": 300, "type": "string" } }, "videoUrls": { "title": "Video URLs", "maxItems": 500, "uniqueItems": true, "type": "array", "description": "YouTube watch, shorts, live, embed, or youtu.be links, or 11-character video IDs. Each distinct input has one maxResults allowance shared by its video, comments, replies, and related videos.", "items": { "minLength": 11, "maxLength": 300, "type": "string" } }, "includeTrending": { "title": "Include trending / popular topics", "type": "boolean", "description": "Discover popular videos from topic hubs for the market selected by gl. This counts as one input, and rows may include trendingTopic." }, "trendingMaxResults": { "title": "Trending candidate cap (optional)", "minimum": 1, "maximum": 200, "type": "integer", "description": "Optional smaller limit on popular-topic candidates, from 1 to 200. If omitted, the smaller of maxResults and 200 is used." }, "maxResults": { "title": "Maximum rows per input", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum rows delivered and billed for each distinct query, channel URL, video URL, or trending input; extra channel, comment, reply, and related-video rows share that allowance. The run also stops at your maximum cost, and Free plan runs are capped at 200 rows.", "default": 70 }, "gl": { "title": "Market country (gl)", "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "type": "string", "description": "Two-letter country code for YouTube search and popular-topic results, such as US, GB, DE, JP, BR, or IN.", "default": "US" }, "hl": { "title": "Interface language (hl)", "minLength": 2, "maxLength": 12, "type": "string", "description": "Language for YouTube results, such as en, de, ja, or pt-BR; this is separate from transcriptLanguage. Leave empty to select a language for the market in gl." }, "proxyCountry": { "title": "Country override", "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "type": "string", "description": "Optional two-letter country override for country-specific collection. Leave empty to use the selected market." }, "uploadDate": { "title": "Upload date filter", "enum": [ "any", "hour", "today", "week", "month", "year" ], "type": "string", "description": "Restrict search to the selected relative publishing period. The Actor does not automatically widen the period.", "default": "any" }, "resultType": { "title": "Result type filter", "enum": [ "any", "video", "channel", "playlist", "movie", "short" ], "type": "string", "description": "Select the YouTube search filter. A playlist filter does not export playlists; rows represent videos, channels, or comments.", "default": "any" }, "duration": { "title": "Duration filter", "enum": [ "any", "short", "medium", "long" ], "type": "string", "description": "Filter search by video length: short is under about 4 minutes, medium is 4–20 minutes, and long is over about 20 minutes.", "default": "any" }, "channelTab": { "title": "Channel tab", "enum": [ "videos", "shorts", "streams", "all" ], "type": "string", "description": "Select videos, shorts, streams, or all tabs. All selected tabs share the channel input's maxResults allowance.", "default": "videos" }, "includeChannelAbout": { "title": "Include channel about", "type": "boolean", "description": "Add a public channel-information row before the channel's video rows. This row is billed at the same price and uses the channel input's allowance.", "default": false }, "useProxyForSearch": { "title": "Use country setting for search", "type": "boolean", "description": "Apply the country setting to search and channel results. Leave off unless you need country-specific results.", "default": false }, "concurrency": { "title": "Enrichment concurrency", "minimum": 1, "maximum": 16, "type": "integer", "description": "Maximum video enrichment operations to perform at once, from 1 to 16. This does not change the row allowance.", "default": 6 }, "includeComments": { "title": "Include comments", "type": "boolean", "description": "Add comments as separate rowType=comment rows, including replies when enabled. Each row is billed and uses the originating input's maxResults allowance.", "default": false }, "maxComments": { "title": "Max top-level comments", "minimum": 0, "maximum": 20000, "type": "integer", "description": "Maximum top-level comments considered per video. Zero uses the 20,000-comment safety limit, but maxResults and the run's remaining allowance take precedence.", "default": 0 }, "includeCommentReplies": { "title": "Include comment replies", "type": "boolean", "description": "Include separate reply rows when includeComments is enabled. Replies use the same allowance and price as other rows.", "default": false }, "maxRepliesPerComment": { "title": "Max replies per comment", "minimum": 0, "maximum": 2000, "type": "integer", "description": "Maximum replies considered per top-level comment. Zero uses the 2,000-reply safety limit, but maxResults and the run's remaining allowance take precedence.", "default": 0 }, "commentSort": { "title": "Comment sort", "enum": [ "top", "newest" ], "type": "string", "description": "Sort comments by top comments or newest first.", "default": "top" }, "includeRelated": { "title": "Include related videos", "type": "boolean", "description": "Add related videos as separate video rows with parentVideoId, parentVideoTitle, and parentVideoUrl. Each row is billed and uses the originating input's allowance.", "default": false }, "maxRelated": { "title": "Max related videos", "minimum": 0, "maximum": 100, "type": "integer", "description": "Maximum related videos considered per source video, from 0 to 100. The originating input's remaining maxResults allowance takes precedence.", "default": 20 }, "scrapeDetails": { "title": "Scrape video details", "type": "boolean", "description": "Request richer video metadata, including publishing dates, descriptions, categories, and counts when available. Use a shortlist to avoid enriching videos you do not need.", "default": false }, "includeTranscript": { "title": "Include transcript", "type": "boolean", "description": "Request available captions as fields on the video row, without an extra row charge. At most 50 segments are retained; joined text is capped at 100,000 characters and may be shortened further.", "default": false }, "transcriptLanguage": { "title": "Transcript language", "minLength": 2, "maxLength": 12, "type": "string", "description": "Preferred caption language, such as en, es, fr, de, ja, or pt. Another available track may be returned; check transcriptLanguage in the output row.", "default": "en" }, "includeEngagement": { "title": "Include engagement metrics", "type": "boolean", "description": "Include available likes, subscriber counts, comment counts, and view counts when scrapeDetails is enabled.", "default": false }, "includeStructure": { "title": "Include content structure", "type": "boolean", "description": "Include available chapters, heatmaps, topics, hashtags, and rich descriptions when scrapeDetails is enabled.", "default": false }, "includePlaybackMeta": { "title": "Include playback metadata", "type": "boolean", "description": "Include available storyboard and playback information when scrapeDetails is enabled. Some videos do not expose this information.", "default": false }, "includeFormats": { "title": "Include stream formats", "type": "boolean", "description": "Include available video and audio format information with playback metadata; this follows includePlaybackMeta unless explicitly set. Format lists may be empty and do not guarantee downloadable media." }, "includeCardsEndscreen": { "title": "Include cards & end screen", "type": "boolean", "description": "Include available in-video cards and end-screen recommendations when scrapeDetails is enabled.", "default": false }, "includeUpdatedMetadata": { "title": "Refresh video metrics", "type": "boolean", "description": "Refresh available counts for collected videos, excluding related videos. Adds updatedMetadata and updates available row values without adding rows.", "default": false }, "includeResolveHandle": { "title": "Resolve channel handles", "type": "boolean", "description": "Resolve channel links or handles to channel identifiers. Use includeChannelAbout to include the resolved fields on channel rows; resolution information also appears in the run summary.", "default": false }, "includeHomeFeed": { "title": "Home feed (not available)", "type": "boolean", "description": "Not available. This option has no effect on collected rows.", "default": false }, "includeGuide": { "title": "Include guide", "type": "boolean", "description": "Add up to 50 topic and category navigation entries for the selected market to the run summary. This does not add rows.", "default": false }, "runMode": { "title": "Collection mode", "enum": [ "real", "fixture" ], "type": "string", "description": "Leave set to real for normal collection. The fixture option is used only by the developer for offline testing.", "default": "real" }, "workerBaseUrl": { "title": "Test URL override", "type": "string", "description": "Leave empty. Used only by the developer for testing." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }