{
  "openapi": "3.0.1",
  "info": {
    "title": "YouTube AI Comments Scraper And Questions Extractor",
    "description": "YouTube comments scraper with AI analysis. Extract comments and replies across one or many videos. Returns extracted questions, sentiment scores and feedback categories per comment. Runs in 128 MB with no proxies required.",
    "version": "1.0",
    "x-build-id": "uJ8rBCsdNzDy6Qf3V"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/sian.agency~youtube-ai-comments-scraper-and-questions-extractor/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-sian.agency-youtube-ai-comments-scraper-and-questions-extractor",
        "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/sian.agency~youtube-ai-comments-scraper-and-questions-extractor/runs": {
      "post": {
        "operationId": "runs-sync-sian.agency-youtube-ai-comments-scraper-and-questions-extractor",
        "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/sian.agency~youtube-ai-comments-scraper-and-questions-extractor/run-sync": {
      "post": {
        "operationId": "run-sync-sian.agency-youtube-ai-comments-scraper-and-questions-extractor",
        "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": {
          "videoUrl": {
            "title": "🔗 YouTube Video URL or ID",
            "type": "string",
            "description": "🎬 **SINGLE VIDEO:** Extract comments from one YouTube video.\n\n✅ **SUPPORTED FORMATS:**\n• Regular URL: https://www.youtube.com/watch?v=VIDEO_ID\n• Shorts URL: https://www.youtube.com/shorts/VIDEO_ID\n• Compact URL: https://youtu.be/VIDEO_ID\n• Direct ID: dQw4w9WgXcQ\n\n💡 **AUTO-EXTRACTION:** We automatically extract the video ID from any URL format!",
            "default": "https://www.youtube.com/watch?v="
          },
          "urls": {
            "title": "📋 Multiple YouTube Video URLs or IDs",
            "type": "array",
            "description": "🚀 **BULK PROCESSING:** Extract comments from multiple YouTube videos.\n\n💰 **TIER-BASED LIMITS:**\n• **FREE users:** Up to 2 videos per run\n• **PAID users:** Unlimited videos\n\n✅ **ACCEPTED FORMATS:**\n• Full YouTube URLs (any format)\n• Direct video IDs only\n• Mixed URLs and IDs\n\n📁 **FILE UPLOAD:**\n• CSV files: Upload .csv with headers (auto-detects URL column)\n• Text files: Upload .txt with URLs (one per line)\n\n📝 **BULK EDIT:** Click \"Bulk edit\" to paste URLs (one per line)\n🔗 **MANUAL ADD:** Use + Add button for individual URLs\n\n⚠️ **IMPORTANT:** Please provide either single URL OR bulk URLs (not both)",
            "default": [
              {
                "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
              }
            ],
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "maxPages": {
            "title": "📄 Max Pages of Comments to Scrape",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "🔢 **Number of comment pages to scrape per video.**\n\n📊 **PAGE SIZE:** Each page contains exactly 20 comments (last page may have fewer if less than 20 remain).\n\n💰 **TIER-BASED LIMITS:**\n• **FREE users:** 1 page (20 comments) per video (for testing)\n• **PAID users:** Unlimited comments and pages\n\n💡 **EXAMPLE:**\n• 1 page = 20 comments\n• 5 pages = 100 comments (default)\n• 10 pages = 200 comments\n\n⚠️ **NOTE:** More pages = longer processing time and higher costs.",
            "default": 5
          },
          "sortBy": {
            "title": "🔄 Comment Sort Order",
            "enum": [
              "newest",
              "top"
            ],
            "type": "string",
            "description": "📊 **Sort comments by:**\n\n🔥 **TOP (Most Liked):** Comments with most likes appear first. Best for finding popular opinions and high-engagement content.\n\n🕐 **NEWEST (Most Recent):** Latest comments appear first. Best for monitoring recent discussions and trending topics.\n\n💡 **Default:** newest",
            "default": "newest"
          },
          "enableAI": {
            "title": "🤖 Enable AI Features",
            "type": "boolean",
            "description": "🧠 **AI-Powered Analysis for Top-Level Comments:**\n\n⚠️ **IMPORTANT:** AI analysis ONLY applies to top-level comments. Replies are included as raw data without AI processing.\n\n✅ **ENABLED (default):**\n• Sentiment analysis (positive/negative/neutral)\n• Question detection and flagging\n• Question categorization (technical, feedback, troubleshooting, comparison, etc.)\n• Priority scoring (1-5 scale)\n• Question summarization\n\n❌ **DISABLED:**\n• Raw comments only (no AI processing)\n• Faster processing\n• Lower costs (no `ai-analysis` charges)\n\n💡 **Use cases:**\n• Enable: Market research, sentiment tracking, FAQ mining, Q&A extraction\n• Disable: Simple comment collection, data archiving",
            "default": true
          },
          "includeReplies": {
            "title": "💬 Include Comment Replies (PAID Only)",
            "type": "boolean",
            "description": "🔄 **Control whether to fetch reply comments.**\n\n✅ **ENABLED:** PAID tier only\n🚫 **FREE tier:** Replies excluded (upgrade required)\n\n• Fetch both parent comments AND their replies\n• **ALL replies are scraped** - no page limit or comment limit\n• Complete thread context for discussions\n• Better for understanding conversations\n• Applies to BOTH normal page scraping AND \"Scrape ALL Comments\" mode\n\n🚫 **IMPORTANT:** Replies are NEVER analyzed with AI (raw data only, regardless of enableAI setting). Only top-level comments receive AI analysis.\n\n❌ **DISABLED:**\n• Fetch only top-level parent comments\n• Faster processing\n• Lower dataset size\n\n💡 **Use cases:**\n• Enable: Community management, conversation analysis, Q&A threads\n• Disable: Quick sentiment analysis, comment volume tracking",
            "default": true
          },
          "scrapeAllComments": {
            "title": "♾️ Scrape ALL Comments",
            "type": "boolean",
            "description": "🌟 **Complete Comment Extraction (PAID Only):**\n\n✅ **ENABLED:**\n• Scrape ALL available comments from video(s)\n• Ignores maxPages limit\n• Processes all pages until no more comments remain\n• Best for comprehensive data collection\n\n💡 Works with `includeReplies` setting - enable both for complete comment threads\n\n❌ **DISABLED (default):**\n• Respects maxPages limit (from input or tier limits)\n• Faster processing\n• Predictable costs\n\n💰 **TIER-BASED BEHAVIOR:**\n• **FREE users:** Still limited to tier restrictions (cannot override)\n• **PAID users:** Unlimited comments when enabled\n\n⚠️ **WARNING:** Enabling this on videos with millions of comments will:\n• Take much longer to process\n• Incur significantly higher costs\n• Generate large datasets\n\n💡 **Use cases:**\n• Enable: Research projects, complete comment archives, data analysis\n• Disable: Quick sampling, testing, cost-controlled scraping",
            "default": false
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}