{
  "openapi": "3.0.1",
  "info": {
    "title": "YouTube Video Scraper by Hashtag With Full Descriptions",
    "description": "The Youtube Video Scraper By Hashtag collects videos tied to any hashtag, including titles, views, likes, comments, creators, and upload details. Export clean JSON or CSV for trend tracking, content research, audience analysis, and marketing insights at scale.",
    "version": "0.1",
    "x-build-id": "9YmRUp2rNA2jCjrFd"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapio~youtube-video-scraper-by-hashtag/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapio-youtube-video-scraper-by-hashtag",
        "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/scrapio~youtube-video-scraper-by-hashtag/runs": {
      "post": {
        "operationId": "runs-sync-scrapio-youtube-video-scraper-by-hashtag",
        "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/scrapio~youtube-video-scraper-by-hashtag/run-sync": {
      "post": {
        "operationId": "run-sync-scrapio-youtube-video-scraper-by-hashtag",
        "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": {
          "searchTerms": {
            "title": "🎯 Search terms — #hashtag, keyword or @handle",
            "type": "array",
            "description": "One or more YouTube search terms. Examples: #chatgpt (hashtag search), chatgpt (plain keyword search), @mkbhd (handle search). Leave empty if you are using the legacy 'hashtags' field below.",
            "items": {
              "type": "string"
            }
          },
          "hashtags": {
            "title": "🔁 hashtags (legacy field — still fully supported)",
            "type": "array",
            "description": "Backward-compatible alias of the field above. If this field is filled in, it wins over 'Search terms'. Kept so that inputs written for the original hashtag scraper keep working unchanged.",
            "items": {
              "type": "string"
            }
          },
          "searchMode": {
            "title": "🧭 How to read a bare keyword",
            "enum": [
              "auto",
              "hashtag"
            ],
            "type": "string",
            "description": "auto = a term is searched exactly as typed (#tag stays a hashtag search, a bare word stays a keyword search). hashtag = every term is forced into a #hashtag search, which is what the original scraper always did.",
            "default": "auto"
          },
          "maxResults": {
            "title": "📊 Videos to collect per search term",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "How many videos to collect for each search term, before filters are applied. YouTube search exhausts at roughly 300 videos per term (measured 301 on #chatgpt), so values above that simply return everything available.",
            "default": 10
          },
          "scrapeShortsOnly": {
            "title": "🩳 Shorts only",
            "type": "boolean",
            "description": "Return only YouTube Shorts. Shorts rows come from YouTube's Shorts shelf, which carries no duration and no description snippet — turn on the description/date lookup below to fill those in.",
            "default": false
          },
          "fetchExactDates": {
            "title": "📝 Fetch full description + exact upload date",
            "type": "boolean",
            "description": "Costs one small JSON request per video. Always fills descriptionFull, descriptionLength, publishedDate (YYYY-MM-DD) and videoAgeDays. The ISO-8601 timestamp (publishDate, uploadDate), category and lengthSeconds come from a YouTube client that refuses Apify's own datacenter IP — turn the proxy on below to get those too. When off, all of these are null and detailsFetched is false.",
            "default": true
          },
          "maxVideoLookups": {
            "title": "🔢 Maximum description lookups per run",
            "minimum": 0,
            "maximum": 2000,
            "type": "integer",
            "description": "Hard ceiling on how many videos get the extra description/date request in one run. Videos beyond the ceiling are still returned, with detailsFetched = false and null detail fields, so 'we never looked' is never confused with 'YouTube had nothing'.",
            "default": 50
          },
          "descriptionKeywords": {
            "title": "🔤 Description / title must contain",
            "type": "array",
            "description": "Case-insensitive. A video is kept when any of these strings appears in its title, its search snippet, or its full description (when it was fetched). Leave empty to keep everything.",
            "items": {
              "type": "string"
            }
          },
          "minDurationSeconds": {
            "title": "⏱️ Minimum duration (seconds)",
            "minimum": 0,
            "maximum": 86400,
            "type": "integer",
            "description": "Drop videos shorter than this. Uses the duration shown in search results, or the exact length from the description lookup. Videos with no known duration are kept."
          },
          "maxDurationSeconds": {
            "title": "⏱️ Maximum duration (seconds)",
            "minimum": 1,
            "maximum": 86400,
            "type": "integer",
            "description": "Drop videos longer than this. Uses the duration shown in search results, or the exact length from the description lookup. Videos with no known duration are kept."
          },
          "publishedWithinDays": {
            "title": "📅 Uploaded within the last N days",
            "minimum": 1,
            "maximum": 3650,
            "type": "integer",
            "description": "Needs the exact upload date, so it only takes effect when the description/date lookup is on. Videos whose upload date could not be read are kept and reported in the log, never guessed from the relative \"4 months ago\" text."
          },
          "proxyConfiguration": {
            "title": "🌐 Proxy configuration",
            "type": "object",
            "description": "Optional but recommended. The proxy is attached to every YouTube request — the search page, every continuation page and every description lookup. Without it YouTube answers the detail lookup from a reduced surface that carries the description and the upload day but no ISO timestamp, no category and no exact length. With a residential proxy all of those fields are returned."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}