{
  "openapi": "3.0.1",
  "info": {
    "title": "YouTube Scraper (Official API) — Videos, Search & Stats",
    "description": "Bring your own free YouTube API key. Get video details and stats (views, likes, comments, duration, tags), YouTube search results, channel uploads and comments from the official YouTube Data API v3 — no scraping, no blocks. $0.40 per 1,000 videos.",
    "version": "0.1",
    "x-build-id": "pY81z5LFqHfOguONB"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/actor-forge~youtube-api-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-actor-forge-youtube-api-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/actor-forge~youtube-api-scraper/runs": {
      "post": {
        "operationId": "runs-sync-actor-forge-youtube-api-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/actor-forge~youtube-api-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-actor-forge-youtube-api-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": {
          "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": "videos"
          },
          "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"
            }
          },
          "searchQueries": {
            "title": "Search queries",
            "type": "array",
            "description": "One or more search terms (search mode). Each page of up to 50 results costs 100 of your 10,000 daily quota units, so a full key's day is about 100 pages (5,000 results).",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "maxResultsPerQuery": {
            "title": "Max results per query",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "Search results per query (search mode). YouTube returns at most about 500 per query. Each 50 = one search page (100 quota units).",
            "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"
          },
          "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}