{
  "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.4",
    "x-build-id": "6ww2hA2XXLyPO7Gun"
  },
  "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 query runs independently and returns up to Max results videos. Use this for topic discovery, SEO research, competitor research, and shortlist building before heavier detail or transcript runs.",
            "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. Supports @handle, UC channel IDs, and common youtube.com channel, c, and user URLs. Use this for creator, brand, media, or competitor channel monitoring.",
            "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. Supports 11-character video IDs and common watch, youtu.be, shorts, embed, and live URL formats. Best for targeted metadata enrichment and transcript extraction after you already have a shortlist.",
            "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 results per query or channel",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "Maximum number of videos to return for each search query or each channel URL. This does not limit direct Video URLs; every listed video URL is processed once. Keep this lower when using Scrape video details or Include transcript.",
            "default": 1
          },
          "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 (split budget across tabs).",
            "default": "videos"
          },
          "includeChannelAbout": {
            "title": "Include channel about",
            "type": "boolean",
            "description": "When scraping channels, also extract about/stats into RUN diagnostics (subscriber text, country, description).",
            "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": "Fetch comments for each video via InnerTube /next with full pagination. Nest comments (+ replies) on each video row. Use with videoUrls or small shortlists for complete coverage.",
            "default": false
          },
          "maxComments": {
            "title": "Max top-level comments",
            "minimum": 0,
            "maximum": 20000,
            "type": "integer",
            "description": "Max top-level comments per video. 0 = fetch all until exhausted (hard safety cap 20000).",
            "default": 0
          },
          "includeCommentReplies": {
            "title": "Include comment replies",
            "type": "boolean",
            "description": "Expand reply threads for each top-level comment (full pagination per thread).",
            "default": true
          },
          "maxRepliesPerComment": {
            "title": "Max replies per comment",
            "minimum": 0,
            "maximum": 2000,
            "type": "integer",
            "description": "Max replies per top-level comment. 0 = all until exhausted (hard safety cap 2000).",
            "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": "Attach related/recommended videos from the watch /next response onto each video row.",
            "default": false
          },
          "maxRelated": {
            "title": "Max related videos",
            "minimum": 0,
            "maximum": 100,
            "type": "integer",
            "description": "Max related videos to attach per source video.",
            "default": 20
          },
          "includeTrending": {
            "title": "Include trending / popular topics",
            "type": "boolean",
            "description": "Discover popular videos for the selected market (gl). YouTube removed classic /feed/trending; this uses topic hubs (gaming, sports, news, podcasts, live, learning, fashion) and tags each row with trendingTopic. Can be used alone or mixed with other sources.",
            "default": false
          },
          "trendingMaxResults": {
            "title": "Trending max results",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "Max videos from topic-hub discovery when Include trending is on.",
            "default": 50
          },
          "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"
          }
        }
      },
      "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}