{ "openapi": "3.0.1", "info": { "title": "YouTube Research Scraper - Videos, Channels & Search", "description": "Collect YouTube video and channel research data for content analysis, competitor monitoring, and lead research. Export structured metadata for automation workflows.", "version": "0.6", "x-build-id": "YuIG9dGnw6TIksP5K" }, "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": { "runMode": { "title": "Run mode", "enum": [ "real", "fixture" ], "type": "string", "description": "Use real for live YouTube collection via the VPS worker. Use fixture for offline smoke tests (no live YouTube traffic).", "default": "real" }, "workerBaseUrl": { "title": "Worker base URL (optional override)", "type": "string", "description": "Optional HTTPS override for the scrape worker. Defaults to Actor env WORKER_BASE_URL or https://yt.opendata.best." }, "searchQueries": { "title": "Search queries", "maxItems": 50, "uniqueItems": true, "type": "array", "description": "YouTube keywords to search. Each distinct query is an independent input with its own maxResults row allowance.", "items": { "type": "string", "minLength": 1, "maxLength": 160 }, "default": [ "ai workflow automation" ] }, "channelUrls": { "title": "Channel URLs", "maxItems": 50, "uniqueItems": true, "type": "array", "description": "Public YouTube channels to scan for recent videos. Each distinct channel URL is an independent input with its own maxResults allowance, shared across the selected channel tabs.", "items": { "type": "string", "minLength": 2, "maxLength": 300, "pattern": "^(@[A-Za-z0-9._-]+|UC[A-Za-z0-9_-]{21,}|https?://(www\\.|m\\.)?youtube\\.com/(@[A-Za-z0-9._-]+|channel/UC[A-Za-z0-9_-]{21,}|c/[A-Za-z0-9._-]+|user/[A-Za-z0-9._-]+).*)$" }, "default": [] }, "videoUrls": { "title": "Video URLs", "maxItems": 500, "uniqueItems": true, "type": "array", "description": "Exact YouTube videos to process. Each distinct video URL or ID is an independent input; its video, comment, reply, and related-video rows share that input's maxResults allowance.", "items": { "type": "string", "minLength": 11, "maxLength": 300, "pattern": "^([A-Za-z0-9_-]{11}|https?://((www\\.|m\\.)?youtube\\.com/(watch\\?.*v=[A-Za-z0-9_-]{11}.*|shorts/[A-Za-z0-9_-]{11}.*|embed/[A-Za-z0-9_-]{11}.*|live/[A-Za-z0-9_-]{11}.*)|youtu\\.be/[A-Za-z0-9_-]{11}.*))$" }, "default": [] }, "maxResults": { "title": "Max billed rows per input", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum Dataset rows delivered and billed for each distinct query, channel URL, video URL, or trending input. Child comment, reply, channel, and related-video rows consume their originating input's allowance. The whole run also stops at your maximum total charge; 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": "YouTube market / region code for search ranking and InnerTube context (ISO-3166 alpha-2), e.g. US, GB, DE, JP, BR, IN.", "default": "US" }, "hl": { "title": "Interface language (hl)", "minLength": 2, "maxLength": 12, "type": "string", "description": "YouTube UI/search language, e.g. en, de, ja, pt-BR. Independent from transcriptLanguage.", "default": "en" }, "proxyCountry": { "title": "Proxy country", "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "type": "string", "description": "Optional residential egress country for detail/transcript (and search when Use proxy for search is on). Defaults to gl when gl/hl are set; otherwise US for enrichment-only runs." }, "uploadDate": { "title": "Upload date filter", "enum": [ "any", "hour", "today", "week", "month", "year" ], "type": "string", "description": "YouTube search upload-date filter.", "default": "any" }, "resultType": { "title": "Result type filter", "enum": [ "any", "video", "channel", "playlist", "movie", "short" ], "type": "string", "description": "YouTube search type filter. Use short for short-form bias.", "default": "any" }, "duration": { "title": "Duration filter", "enum": [ "any", "short", "medium", "long" ], "type": "string", "description": "YouTube search duration filter (short under ~4m, long over ~20m).", "default": "any" }, "channelTab": { "title": "Channel tab", "enum": [ "videos", "shorts", "streams", "all" ], "type": "string", "description": "Which channel tab to scrape: videos, shorts, streams, or all. When all is selected, the tabs share that channel input's maxResults allowance.", "default": "videos" }, "includeChannelAbout": { "title": "Include channel about", "type": "boolean", "description": "When scraping channel URLs, emit one standalone channel row with public about/stats fields before that channel’s video rows.", "default": false }, "useProxyForSearch": { "title": "Use proxy for search", "type": "boolean", "description": "Route search/channel HTML through residential proxy. Off by default (datacenter InnerTube/HTML); enable for geo-sensitive SERP.", "default": false }, "concurrency": { "title": "Enrichment concurrency", "minimum": 1, "maximum": 16, "type": "integer", "description": "Max parallel detail/transcript/comment enrichments (1–16). Higher is faster but uses more proxy/egress.", "default": 6 }, "includeComments": { "title": "Include comments", "type": "boolean", "description": "Emit comments and replies as standalone rowType=comment rows. They consume the maxResults allowance of the query, channel, video, or trending input that produced the parent video.", "default": false }, "maxComments": { "title": "Max top-level comments", "minimum": 0, "maximum": 20000, "type": "integer", "description": "Maximum top-level comments considered per video. 0 means source-exhaustive within safety caps, but the originating input's maxResults allowance always wins.", "default": 0 }, "includeCommentReplies": { "title": "Include comment replies", "type": "boolean", "description": "Emit reply rows after their top-level comment while row budget remains.", "default": true }, "maxRepliesPerComment": { "title": "Max replies per comment", "minimum": 0, "maximum": 2000, "type": "integer", "description": "Maximum replies considered per top-level comment. 0 means source-exhaustive within safety caps, but maxResults always wins.", "default": 0 }, "commentSort": { "title": "Comment sort", "enum": [ "top", "newest" ], "type": "string", "description": "YouTube comment sort order.", "default": "top" }, "includeRelated": { "title": "Include related videos", "type": "boolean", "description": "Emit related/recommended videos as standalone rowType=video rows with parent video fields.", "default": false }, "maxRelated": { "title": "Max related videos", "minimum": 0, "maximum": 100, "type": "integer", "description": "Maximum related-video rows considered per source video, inside the originating input's maxResults allowance.", "default": 20 }, "includeTrending": { "title": "Include trending / popular topics", "type": "boolean", "description": "Discover popular videos for the selected market (gl). Trending is one independent input with its own maxResults allowance. YouTube removed classic /feed/trending; this uses topic hubs and tags each row with trendingTopic.", "default": false }, "trendingMaxResults": { "title": "Trending candidate cap (optional)", "minimum": 1, "maximum": 200, "type": "integer", "description": "Optional smaller cap on trending candidates. When omitted, the smaller of maxResults and the 200-candidate safety cap is used." }, "scrapeDetails": { "title": "Scrape video details", "type": "boolean", "description": "Fetch richer metadata for each video, such as exact publish date, category, fuller description, and refreshed view count when available. Best used on smaller runs or shortlisted Video URLs.", "default": false }, "includeTranscript": { "title": "Include transcript", "type": "boolean", "description": "Attempt to fetch timestamped captions and full transcript text for each video. Transcript fields are added only when captions are available and can be fetched. This is the heaviest mode, so it is best for targeted Video URLs or small shortlists.", "default": false }, "transcriptLanguage": { "title": "Transcript language", "minLength": 2, "maxLength": 12, "type": "string", "description": "Preferred transcript language code, for example en, es, fr, de, ja, or pt. If the requested language is unavailable, the Actor can fall back to the first available caption track.", "default": "en" }, "includeEngagement": { "title": "Include engagement metrics", "type": "boolean", "description": "Backfill likeCount/subscriberCount/commentCountExact/viewCountExact from /next engagement panels.", "default": true }, "includeStructure": { "title": "Include content structure", "type": "boolean", "description": "Backfill chapters/heatmap/topics/hashtags/descriptionRich/structuredDescription.", "default": true }, "includePlaybackMeta": { "title": "Include playback metadata", "type": "boolean", "description": "Backfill storyboards/playbackTracking/playerConfig from the player response.", "default": true }, "includeFormats": { "title": "Include stream formats", "type": "boolean", "description": "Backfill streamingData formats/adaptiveFormats (manifest URLs, itag, quality) from the player response. Defaults to the Include playback metadata value; set false to drop the formats list. Many popular videos return no stream URLs to anonymous clients, so this list may be empty on locked videos." }, "includeCardsEndscreen": { "title": "Include cards & end screen", "type": "boolean", "description": "Backfill in-video cards and end-screen recommendations.", "default": true }, "includeUpdatedMetadata": { "title": "Refresh video metrics", "type": "boolean", "description": "Re-check viewCount and likeCount for each collected video (not related videos) with one light request per video. Fresh values replace the row's values; the raw response is stored in updatedMetadata.", "default": false }, "includeResolveHandle": { "title": "Resolve channel handles", "type": "boolean", "description": "Resolve each channel URL or @handle to its channel ID. Adds resolvedChannelId and resolvedCanonicalUrl to channel rows (needs Include channel about) and to run diagnostics.", "default": false }, "includeHomeFeed": { "title": "Include home feed", "type": "boolean", "description": "Not implemented yet; has no effect. Kept only so existing inputs that set it stay valid.", "default": false }, "includeGuide": { "title": "Include guide", "type": "boolean", "description": "Fetch the YouTube guide (topic and category navigation) once per run for the selected market and save the first 50 entries in run diagnostics. Adds no rows.", "default": false } } }, "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 } } } } } } } } } }