{
  "openapi": "3.0.1",
  "info": {
    "title": "YouTube Comments Scraper: Comment Analytics & Keyword Search",
    "description": "YouTube Comments Scraper: Extract comments by keyword with authors, text, timestamps, likes, replies, and engagement data. Analyze audience sentiment, recurring topics, viewer feedback, and comment trends to support content research, competitor analysis, and YouTube marketing.",
    "version": "0.1",
    "x-build-id": "Were07AXljlDi0Wi4"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/api-empire~youtube-comments-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-api-empire-youtube-comments-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-comments-scraper/runs": {
      "post": {
        "operationId": "runs-sync-api-empire-youtube-comments-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-comments-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-api-empire-youtube-comments-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": {
          "targetUrls": {
            "title": "🎯 Videos, Channels & Playlists",
            "type": "array",
            "description": "📋 Add YouTube video URLs or 11-char video IDs, CHANNEL URLs (e.g. https://www.youtube.com/@MrBeast or /channel/UC...), or PLAYLIST URLs (e.g. https://www.youtube.com/playlist?list=...). Channels and playlists are auto-detected and expanded to their member videos from the channel's Videos tab / the playlist's video list (capped by Max Videos per Channel/Playlist below); comments are then scraped from every resolved video. (Base key `startUrls` is still accepted as a fallback.)",
            "items": {
              "type": "string"
            }
          },
          "commentLimit": {
            "title": "📊 Max Comments per Video",
            "minimum": 0,
            "type": "integer",
            "description": "🔢 Maximum number of comments to FETCH per video (0 = no limit / all available). This is the fetch budget the engagement/date/keyword filters below then narrow down — filters never make the actor fetch fewer comments, only push fewer rows. (Base key `maxComments` still works.)"
          },
          "commentOrder": {
            "title": "📑 Comment Sort Order",
            "enum": [
              "top",
              "newest"
            ],
            "type": "string",
            "description": "⬆️ top — most liked/relevant first (YouTube default). newest — most recent first. (Base key `sortOrder` still works.)"
          },
          "minLikes": {
            "title": "👍 Minimum Likes",
            "minimum": 0,
            "type": "integer",
            "description": "🚦 Drop comments with fewer than this many likes (voteCount). Example: minLikes=10 keeps only comments with 10+ likes. Default 0 = no floor. Verified live: a real run drops every low-like comment and keeps only qualifying ones.",
            "default": 0
          },
          "minReplyCount": {
            "title": "↩️ Minimum Reply Count",
            "minimum": 0,
            "type": "integer",
            "description": "🚦 Drop comments with fewer than this many replies. Example: minReplyCount=2 keeps only comments with 2+ replies. Default 0 = no floor.",
            "default": 0
          },
          "oldestCommentDate": {
            "title": "📅 Oldest Comment Date",
            "type": "string",
            "description": "⏳ Only keep comments published ON OR AFTER this date. Accepts an ABSOLUTE date (e.g. 2026-06-01) OR a RELATIVE shorthand (e.g. '2 weeks', '3 months', '1 year'). Because YouTube's comment API never returns an exact timestamp — only relative text like '2 weeks ago' — the actual comparison date is an ESTIMATE anchored to the run's scrapedAt time; every row carries dateEstimated:true, never presented as exact."
          },
          "newestCommentDate": {
            "title": "📅 Newest / Cutoff Comment Date",
            "type": "string",
            "description": "⏳ Only keep comments published ON OR BEFORE this date (upper bound — useful to exclude very recent chatter or bound a historical window). Same absolute-or-relative + estimated-date rules as Oldest Comment Date above."
          },
          "keywordSearch": {
            "title": "🔍 Keyword Search",
            "type": "array",
            "description": "✅ Only keep comments containing AT LEAST ONE of these keywords/phrases (case-insensitive). Leave empty to keep all comments (subject to the other filters). Example: [\"love it\", \"amazing\"].",
            "items": {
              "type": "string"
            }
          },
          "excludeKeywords": {
            "title": "🚫 Exclude Keywords",
            "type": "array",
            "description": "❌ Drop any comment containing ANY of these keywords/phrases (case-insensitive), e.g. spam/profanity terms. Example: [\"subscribe to my channel\", \"http\"].",
            "items": {
              "type": "string"
            }
          },
          "maxVideosPerChannel": {
            "title": "📺 Max Videos per Channel",
            "minimum": 0,
            "type": "integer",
            "description": "🔢 When a CHANNEL URL is provided, expand at most this many videos from its Videos tab before scraping comments on each. Default 5.",
            "default": 5
          },
          "maxVideosPerPlaylist": {
            "title": "🎞️ Max Videos per Playlist",
            "minimum": 0,
            "type": "integer",
            "description": "🔢 When a PLAYLIST URL is provided, expand at most this many member videos (0 = all) before scraping comments on each. Default 10.",
            "default": 10
          },
          "includeVideoRollup": {
            "title": "🧮 Include Per-Video Engagement Rollup",
            "type": "boolean",
            "description": "📈 Emit one extra summary row per video (type=\"video_rollup\") with avgLikesPerComment, replyRatio, and the topComment by likes — computed over ALL comments fetched for that video (independent of the filters above), for at-a-glance brand/community monitoring across many videos. Default on.",
            "default": true
          },
          "proxySettings": {
            "title": "🌐 Proxy Settings",
            "type": "object",
            "description": "🛡️ Configure proxy settings for scraping. By default, no proxy is used. If you encounter rate limits or blocks, enable Apify Proxy — the actor automatically escalates none → datacenter → residential on a block. (Base key `proxyConfiguration` still works.)"
          },
          "commentLanguage": {
            "title": "🌍 Comment Language (hl)",
            "type": "string",
            "description": "🈺 Language code passed to YouTube for the comment request (affects relative-time phrasing like 'ago'). Default en-GB. (Base key `language` still works.)"
          },
          "commentRegion": {
            "title": "🌎 Comment Region (gl)",
            "type": "string",
            "description": "🈺 Region code passed to YouTube for the comment request. Default US. (Base key `region` still works.)"
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}