{
  "openapi": "3.0.1",
  "info": {
    "title": "YouTube Search Scraper (Official API) — Videos by Keyword",
    "description": "Bring your own free YouTube API key. YouTube search by keyword with sort, date, region, language and length filters — every result enriched with views, likes, comments, duration and tags via the official YouTube Data API v3. No scraping, no blocks. $0.30 per 1,000 results.",
    "version": "0.1",
    "x-build-id": "suuWdh8hhEBwZimgf"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/actor-forge~youtube-search-api/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-actor-forge-youtube-search-api",
        "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/actor-forge~youtube-search-api/runs": {
      "post": {
        "operationId": "runs-sync-actor-forge-youtube-search-api",
        "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/actor-forge~youtube-search-api/run-sync": {
      "post": {
        "operationId": "run-sync-actor-forge-youtube-search-api",
        "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": {
          "apiKey": {
            "title": "YouTube API key (your own, free)",
            "type": "string",
            "description": "Required. Your own free YouTube Data API v3 key (starts with AIza). Get one in about a minute: console.cloud.google.com → create a project → APIs & Services → Library → enable \"YouTube Data API v3\" → Credentials → Create credentials → API key. No billing account is needed, and the free quota is 10,000 units per day. The key is stored encrypted by Apify, used only for this run's calls to googleapis.com, and never logged or written to the output."
          },
          "mode": {
            "title": "What to get",
            "enum": [
              "videos",
              "search",
              "channel",
              "comments"
            ],
            "type": "string",
            "description": "videos: details and stats for video URLs/IDs (1 quota unit per 50 videos). search: YouTube search results, enriched with full video details (100 units per page of 50). channel: channel stats plus every upload (about 2 units per 50 videos). comments: comments on videos, author names stripped (1 unit per 100 comments).",
            "default": "search"
          },
          "searchQueries": {
            "title": "Search queries",
            "type": "array",
            "description": "One or more search terms. Each page of up to 50 results costs 100 of your 10,000 daily quota units (about 5,000 results per free key per day). YouTube returns at most about 500 results per query.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "maxResultsPerQuery": {
            "title": "Max results per query",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "Search results per query. YouTube returns at most about 500 per query. Each 50 = one search page (100 quota units + 1 for video details).",
            "default": 50
          },
          "order": {
            "title": "Sort search by",
            "enum": [
              "relevance",
              "date",
              "viewCount",
              "rating",
              "title"
            ],
            "type": "string",
            "description": "search.list order (search mode).",
            "default": "relevance"
          },
          "searchType": {
            "title": "Search for",
            "enum": [
              "video",
              "channel"
            ],
            "type": "string",
            "description": "video: video rows with full details. channel: channel rows with subscriber, video and view counts (search mode).",
            "default": "video"
          },
          "publishedAfter": {
            "title": "Published after",
            "type": "string",
            "description": "Optional date (YYYY-MM-DD). In search mode, filters results; in channel mode, only uploads on or after it (and paging stops at older videos, saving quota).",
            "default": ""
          },
          "publishedBefore": {
            "title": "Published before",
            "type": "string",
            "description": "Optional date (YYYY-MM-DD) for search mode.",
            "default": ""
          },
          "regionCode": {
            "title": "Region code",
            "type": "string",
            "description": "Optional 2-letter country code (US, GB, DE …): search results available in that country (search mode).",
            "default": ""
          },
          "relevanceLanguage": {
            "title": "Relevance language",
            "type": "string",
            "description": "Optional ISO 639-1 language code (en, es, de …): results most relevant to that language (search mode).",
            "default": ""
          },
          "videoDuration": {
            "title": "Video length",
            "enum": [
              "any",
              "short",
              "medium",
              "long"
            ],
            "type": "string",
            "description": "Filter search results by duration (search mode, videos only). short < 4 min, medium 4–20 min, long > 20 min.",
            "default": "any"
          },
          "videoUrls": {
            "title": "Video URLs or IDs",
            "type": "array",
            "description": "Videos for the videos and comments modes: watch URLs, youtu.be links, Shorts, embed or live URLs, or bare 11-character IDs. Duplicates are removed. videos.list takes 50 IDs per call.",
            "items": {
              "type": "string"
            }
          },
          "channels": {
            "title": "Channels",
            "type": "array",
            "description": "Channel URLs (youtube.com/@handle, /channel/UC…, /user/name), @handles or channel IDs (UC…), for channel mode. Each gives one channel row plus its uploads.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "maxVideosPerChannel": {
            "title": "Max videos per channel",
            "minimum": 0,
            "maximum": 20000,
            "type": "integer",
            "description": "Newest uploads per channel (channel mode). 0 = channel row only. Every 50 videos cost about 2 quota units.",
            "default": 100
          },
          "includeShorts": {
            "title": "Include Shorts",
            "type": "boolean",
            "description": "Channel mode. The API does not flag Shorts, so this uses a heuristic (3 minutes or less, not live): turning it off also drops regular videos that short.",
            "default": true
          },
          "maxCommentsPerVideo": {
            "title": "Max comments per video",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "Top-level comments per video (comments mode). Replies are not counted here; they are capped separately by Max replies per comment. 100 top-level comments per quota unit.",
            "default": 100
          },
          "includeReplies": {
            "title": "Include replies",
            "type": "boolean",
            "description": "Also return replies (comments mode), up to Max replies per comment per thread. Each reply is its own comment-result row, linked by parentId.",
            "default": false
          },
          "maxRepliesPerComment": {
            "title": "Max replies per comment",
            "minimum": 0,
            "maximum": 1000,
            "type": "integer",
            "description": "With Include replies on: at most this many replies per top-level comment (comments mode), so one huge thread cannot eat the run. 0 = no replies. Up to 5 replies come free with the thread call; more cost 1 quota unit per 100.",
            "default": 20
          },
          "commentOrder": {
            "title": "Comment order",
            "enum": [
              "time",
              "relevance"
            ],
            "type": "string",
            "description": "time: newest first. relevance: YouTube's top comments.",
            "default": "time"
          },
          "searchTerms": {
            "title": "Only comments containing",
            "type": "string",
            "description": "Optional keyword filter applied by YouTube to the comments (comments mode).",
            "default": ""
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}