{
  "openapi": "3.0.1",
  "info": {
    "title": "YouTube Search Scraper — Videos, Channels & Playlists",
    "description": "Scrape YouTube search results (videos, channels, playlists, movies) without cookies or the API. Title, channel, views, duration, publish date, thumbnails. Full filter support. HTTP + residential proxy primary, SerpApi last-resort fallback. MCP-ready.",
    "version": "0.1",
    "x-build-id": "4br8jIfeKWDzRtK0s"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/khadinakbar~youtube-search-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-khadinakbar-youtube-search-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/khadinakbar~youtube-search-scraper/runs": {
      "post": {
        "operationId": "runs-sync-khadinakbar-youtube-search-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/khadinakbar~youtube-search-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-khadinakbar-youtube-search-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",
        "required": [
          "searchQueries"
        ],
        "properties": {
          "searchQueries": {
            "title": "Search queries",
            "type": "array",
            "description": "One or more free-text YouTube search terms, exactly as you would type them into the YouTube search bar (e.g. 'how to bake sourdough'). Each query is scraped independently and results are merged into one dataset. Defaults to a single example query. This is NOT a YouTube URL or video ID — for a specific video's comments or transcript use the dedicated youtube-comments-scraper or youtube-transcript-extractor actors.",
            "items": {
              "type": "string"
            }
          },
          "maxResultsPerQuery": {
            "title": "Max results per query",
            "minimum": 1,
            "maximum": 2000,
            "type": "integer",
            "description": "Maximum number of results to return for each search query, across pagination. The actor stops paginating once this many items are collected. Defaults to 50; set higher for deep scrapes (each result is billed). NOT a global cap across all queries — it applies per individual query.",
            "default": 50
          },
          "resultType": {
            "title": "Result type filter",
            "enum": [
              "all",
              "video",
              "channel",
              "playlist",
              "movie"
            ],
            "type": "string",
            "description": "Restrict results to a single content type on YouTube. 'all' returns the natural mix YouTube serves (videos, channels, playlists). Choose 'video', 'channel', 'playlist', or 'movie' to narrow the search. Defaults to 'all'.",
            "default": "all"
          },
          "sortBy": {
            "title": "Sort by",
            "enum": [
              "relevance",
              "uploadDate",
              "viewCount",
              "rating"
            ],
            "type": "string",
            "description": "Ordering of the search results, mirroring YouTube's own sort options. 'relevance' is YouTube's default ranking; the others sort by upload recency, total view count, or rating. Defaults to 'relevance'. Note YouTube only sorts the first page reliably — deep pagination reverts toward relevance.",
            "default": "relevance"
          },
          "uploadDate": {
            "title": "Upload date filter",
            "enum": [
              "any",
              "lastHour",
              "today",
              "thisWeek",
              "thisMonth",
              "thisYear"
            ],
            "type": "string",
            "description": "Restrict to videos uploaded within a recent time window, matching YouTube's 'Upload date' filter chips. 'any' applies no time filter. Only meaningful when results include videos. Defaults to 'any'.",
            "default": "any"
          },
          "duration": {
            "title": "Video duration filter",
            "enum": [
              "any",
              "short",
              "medium",
              "long"
            ],
            "type": "string",
            "description": "Restrict videos by length, matching YouTube's 'Duration' filter. 'short' is under 4 minutes, 'medium' is 4–20 minutes, 'long' is over 20 minutes. 'any' applies no duration filter and is the default.",
            "default": "any"
          },
          "features": {
            "title": "Feature filters",
            "type": "array",
            "description": "Optional YouTube feature filters, applied together (e.g. ['hd','subtitles']). Mirrors YouTube's 'Features' filter chips such as Live, 4K, HD, Subtitles/CC, Creative Commons, 360°, VR180, 3D, HDR, Location, Purchased. Leave empty for no feature filtering (default). Combining many feature filters can sharply reduce result counts.",
            "items": {
              "type": "string",
              "enum": [
                "live",
                "fourK",
                "hd",
                "subtitles",
                "creativeCommons",
                "threeSixty",
                "vr180",
                "threeD",
                "hdr",
                "location",
                "purchased"
              ],
              "enumTitles": [
                "Live",
                "4K",
                "HD",
                "Subtitles/CC",
                "Creative Commons",
                "360°",
                "VR180",
                "3D",
                "HDR",
                "Location",
                "Purchased"
              ]
            },
            "default": []
          },
          "country": {
            "title": "Country (gl)",
            "type": "string",
            "description": "Two-letter ISO country code used as YouTube's geo context (gl parameter), affecting which regional results and trending content appear (e.g. 'US', 'GB', 'DE'). Also used as the residential proxy country. Defaults to 'US'. NOT a language code — see 'language' for that.",
            "default": "US"
          },
          "language": {
            "title": "Language (hl)",
            "type": "string",
            "description": "Two-letter ISO language code used as YouTube's interface/content language (hl parameter), affecting titles of localized metadata and relative date strings (e.g. 'en', 'es', 'de'). Defaults to 'en'. NOT a country code — see 'country' for that.",
            "default": "en"
          },
          "rawSpToken": {
            "title": "Raw filter token (advanced)",
            "type": "string",
            "description": "Advanced override: a raw YouTube 'sp' filter token (the value after sp= in a filtered YouTube search URL). When set, it overrides the resultType/sortBy/uploadDate/duration/features fields entirely. Leave blank to let the actor build the token for you. Only for power users who copied a token from a complex YouTube filter URL.",
            "default": ""
          },
          "serpApiKey": {
            "title": "SerpApi key (optional fallback)",
            "type": "string",
            "description": "Optional SerpApi API key used ONLY as a last-resort fallback when YouTube blocks the direct HTTP scrape on every retry. Bring your own key from serpapi.com to make fallback free of the managed fallback fee. If left blank, the actor uses its managed SerpApi key (billed per fallback query). Stored as a secret and never logged."
          },
          "fallbackMode": {
            "title": "SerpApi fallback mode",
            "enum": [
              "auto",
              "never",
              "always"
            ],
            "type": "string",
            "description": "Controls when the SerpApi fallback engages. 'auto' (default) uses direct HTTP + residential proxy first and only falls back to SerpApi after all retries are exhausted. 'never' disables the fallback entirely (run fails honestly if YouTube blocks). 'always' skips direct scraping and uses SerpApi for every query (highest reliability, highest cost).",
            "default": "auto"
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Proxy settings for the direct HTTP scrape. Residential proxies are strongly recommended and enabled by default — datacenter IPs are reliably blocked by YouTube. The country is auto-aligned to the 'country' field when not overridden here.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}