{
  "openapi": "3.0.1",
  "info": {
    "title": "YouTube Metadata Scraper With Creator Contact Leads",
    "description": "YouTube Metadata Scraper extracts public video and creator data, including titles, descriptions, views, likes, upload dates, channel details, and publicly available contact leads. Build structured datasets for content research, influencer discovery, lead generation, and competitor analysis.",
    "version": "0.1",
    "x-build-id": "7PAtsMALDMbUdUc1S"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/api-empire~youtube-metadata-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-api-empire-youtube-metadata-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/api-empire~youtube-metadata-scraper/runs": {
      "post": {
        "operationId": "runs-sync-api-empire-youtube-metadata-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/api-empire~youtube-metadata-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-api-empire-youtube-metadata-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": {
          "urls": {
            "title": "🎥 Video links or video IDs",
            "type": "array",
            "description": "One per line. Accepts `youtube.com/watch?v=…`, `youtu.be/…`, `/shorts/…`, `/live/…`, `/embed/…` or the raw video ID. Leave empty to prospect by keyword instead.",
            "items": {
              "type": "string"
            }
          },
          "keywords": {
            "title": "🧲 Prospecting search terms",
            "type": "array",
            "description": "One niche phrase per line, e.g. `home barista setup` or `saas onboarding tutorial`. Every video found is resolved to its channel and enriched.",
            "items": {
              "type": "string"
            }
          },
          "max_results_per_keyword": {
            "title": "📈 Videos to pull per search term",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "How deep to page each search term. The value is a **cap, not a promise**: YouTube stops handing out continuation tokens somewhere around **130–480 videos** per term, so anything above that simply stops early. Remember that many videos share one channel — 30 videos was 15 unique channels in testing.",
            "default": 20
          },
          "sort_order": {
            "title": "🥇 Search result ranking",
            "enum": [
              "relevance",
              "view_count",
              "upload_date",
              "rating"
            ],
            "type": "string",
            "description": "Applies to keyword prospecting only. YouTube retired the *upload date* and *rating* sorts — they are kept here for compatibility and the run logs a warning when you pick one, because results will come back in relevance order.",
            "default": "relevance"
          },
          "includeChannelContacts": {
            "title": "📇 Open the creator's About panel",
            "type": "boolean",
            "description": "Adds the real `@handle`, canonical URL, country, join date, exact lifetime views/videos, the full external-link list, the socials map and the business-email gate flag. Turn off for metadata-only runs.",
            "default": true
          },
          "emailSources": {
            "title": "✉️ Where to look for an email address",
            "uniqueItems": true,
            "type": "array",
            "description": "Addresses are only ever **read out of scraped text** — nothing is guessed or pattern-generated. The winning source is recorded in `channelEmailSource` so you can tell a stated business contact from an incidental mention. YouTube's own business email is sign-in gated and is never included here.",
            "items": {
              "type": "string",
              "enum": [
                "channel_about_bio",
                "channel_about_page",
                "video_description"
              ],
              "enumTitles": [
                "📝 Channel About bio text",
                "📄 Anywhere on the About panel payload",
                "🎬 The video's own description"
              ]
            },
            "default": [
              "channel_about_bio",
              "channel_about_page",
              "video_description"
            ]
          },
          "maxChannelsToEnrich": {
            "title": "💰 Cap the number of channels enriched",
            "minimum": 0,
            "type": "integer",
            "description": "Hard budget on About requests. `0` = no cap. Once the cap is reached, remaining rows still carry full video metadata but no lead block.",
            "default": 0
          },
          "onlyChannelsWithContact": {
            "title": "🧹 Keep only channels with a contact signal",
            "type": "boolean",
            "description": "A contact signal is a scraped email, a social profile link, a website link, or a configured (sign-in gated) business email.",
            "default": false
          },
          "requireSocialProfile": {
            "title": "📱 Require at least one social profile",
            "type": "boolean",
            "description": "Drops channels whose About panel has no recognised social platform link (Instagram, X/Twitter, TikTok, LinkedIn, Discord, Patreon, Twitch, Threads, Telegram, …).",
            "default": false
          },
          "requireEmail": {
            "title": "✉️ Require a scraped email address",
            "type": "boolean",
            "description": "Strictest filter. Keeps only rows where a literal email address was found in the text. Expect this to discard the large majority of channels — most creators publish links, not addresses.",
            "default": false
          },
          "minChannelSubscribers": {
            "title": "👥 Minimum subscriber count (approximate)",
            "minimum": 0,
            "type": "integer",
            "description": "Filters on `channelSubscribersCount`, which is de-abbreviated from YouTube's rounded label (`4.24M` → `4240000`). Exact subscriber counts are not published anywhere logged-out, so treat this as a band, not a precise threshold. `0` = no floor.",
            "default": 0
          },
          "channelCreatedAfter": {
            "title": "📆 Channel created after",
            "type": "string",
            "description": "Keep only newer channels. Absolute (`2020-01-01`) or relative (`3 years`). Matched against `channelCreatedAt`, parsed from the About panel's join date."
          },
          "channelCreatedBefore": {
            "title": "📆 Channel created before",
            "type": "string",
            "description": "Keep only established channels. Absolute (`2018-12-31`) or relative (`5 years`). Rows with no readable join date are never dropped by this filter."
          },
          "max_comments": {
            "title": "💬 Top-level comments per video",
            "minimum": 0,
            "maximum": 5000,
            "type": "integer",
            "description": "Useful for reading the audience before you reach out. Set **0** to skip comments entirely and keep runs fast and rows small.",
            "default": 2
          },
          "include_transcripts": {
            "title": "📥 Attach caption text",
            "type": "boolean",
            "description": "Downloads the caption track when YouTube exposes one. Byte-identical duplicate tracks are removed automatically.",
            "default": true
          },
          "transcript_format": {
            "title": "🧾 Caption shape",
            "enum": [
              "text",
              "timestamps"
            ],
            "type": "string",
            "description": "Plain text is easiest to read; timed segments are better for clipping and search.",
            "default": "text"
          },
          "include_english_auto": {
            "title": "🤖 Also accept auto-generated English",
            "type": "boolean",
            "description": "Includes YouTube's machine captions when the creator uploaded none.",
            "default": false
          },
          "include_non_english": {
            "title": "🌍 Also accept non-English tracks",
            "type": "boolean",
            "description": "A popular video can expose **38+** language tracks. The language cap below is what keeps that from blowing up your run time and row size.",
            "default": false
          },
          "maxTranscriptLanguages": {
            "title": "🔢 Caption tracks per video",
            "minimum": 1,
            "maximum": 40,
            "type": "integer",
            "description": "Hard cap on how many distinct caption tracks are stored per video, applied after duplicates are removed.",
            "default": 3
          },
          "transcriptTimeoutSeconds": {
            "title": "⏳ Caption time budget per video",
            "minimum": 15,
            "maximum": 600,
            "type": "integer",
            "description": "Wall-clock budget for caption downloads on one video. When it runs out the row is still saved — just without captions.",
            "default": 90
          },
          "proxyConfiguration": {
            "title": "🔒 Proxy configuration",
            "type": "object",
            "description": "Residential + United States is the configuration these endpoints were verified on. Datacenter exits were measured at roughly **83% logged-out walls** and **zero** caption tracks.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ],
              "apifyProxyCountry": "US"
            }
          },
          "allowProxyAutoUpgrade": {
            "title": "🛟 Auto-upgrade to residential when no proxy is set",
            "type": "boolean",
            "description": "When the run starts with no proxy selected, switch to Apify Residential (US) and log why. Turn this off to force the exact network you configured, accepting the much higher block rate.",
            "default": true
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}