{
  "openapi": "3.0.1",
  "info": {
    "title": "YouTube Search Scraper By Upload Date, Duration & Type",
    "description": "Extract YouTube search result data in seconds. Gather video titles, links, channels, view counts, thumbnails, and upload dates from keyword searches to power research, trend analysis, or content monitoring workflows.",
    "version": "0.1",
    "x-build-id": "d4imlh0eEWTS5yabd"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapier~youtube-search-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapier-youtube-search-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/scrapier~youtube-search-scraper/runs": {
      "post": {
        "operationId": "runs-sync-scrapier-youtube-search-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/scrapier~youtube-search-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-scrapier-youtube-search-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": {
          "searchTerms": {
            "title": "🔎 Search terms",
            "type": "array",
            "description": "📝 One search term per line, exactly as you would type it into YouTube's search box. Example: « python programming », « cold brew review ». Legacy runs that send `queries` instead still work.",
            "items": {
              "type": "string"
            },
            "default": [
              "python programming"
            ]
          },
          "resultsPerTerm": {
            "title": "📊 Results per search term",
            "minimum": 1,
            "maximum": 2000,
            "type": "integer",
            "description": "📈 How many results to collect for each search term (1–2000). ⚠️ At `Extraction depth = Full` each row costs roughly 587 KB of RESIDENTIAL proxy traffic, so 2000 results is about 1.2 GB per term. At `Fast` a row costs about 2 KB. Default is 10.",
            "default": 10
          },
          "orderResultsBy": {
            "title": "↕️ Order results by",
            "enum": [
              "relevance",
              "date",
              "viewCount",
              "rating"
            ],
            "type": "string",
            "description": "🔀 Ordering to request. ✅ « View count » is also re-sorted by us afterwards, so the rows come back in strict descending order. 📅 « Upload date » is re-sorted by us only at `Extraction depth = Full`, because exact publish timestamps are not present in fast results. ⭐ « Rating » is passed to YouTube but cannot be re-sorted or verified — YouTube publishes no rating figure. Legacy key `sortBy` is still accepted.",
            "default": "relevance"
          },
          "publishedWithin": {
            "title": "📅 Uploaded within",
            "enum": [
              "",
              "lastHour",
              "today",
              "thisWeek",
              "thisMonth",
              "thisYear"
            ],
            "type": "string",
            "description": "📆 Keep only results uploaded inside this window. Verified: « This week » returned a completely different set of videos than an unfiltered search (0 of 8 IDs in common). Legacy key `uploadDate` is still accepted.",
            "default": ""
          },
          "videoLength": {
            "title": "⏱️ Video length",
            "enum": [
              "",
              "short",
              "medium",
              "long"
            ],
            "type": "string",
            "description": "⏱️ Keep only videos in this length band. Verified against real durations: Short returned 66–144 s, Medium returned 247–1129 s, Long returned 3606–57468 s. Applies to video results only. Legacy key `duration` is still accepted.",
            "default": ""
          },
          "resultKind": {
            "title": "📺 Kind of result to return",
            "enum": [
              "video",
              "channel",
              "playlist",
              "movie"
            ],
            "type": "string",
            "description": "🎬 Videos, 📢 channels or 📂 playlists. Channel rows carry subscriber count, handle and verification; playlist rows carry the playlist's video count and owning channel. 🎞️ « Movie » is offered for compatibility and is very rarely populated by YouTube search. Legacy key `type` is still accepted.",
            "default": "video"
          },
          "onlyWithSubtitles": {
            "title": "💬 Only videos with subtitles / CC",
            "type": "boolean",
            "description": "💬 Restrict to videos that carry closed captions. Verified: only 4 of 8 IDs matched an unfiltered search, so the filter genuinely narrows results. Video results only.",
            "default": false
          },
          "onlyCreativeCommons": {
            "title": "⚖️ Only Creative Commons licensed",
            "type": "boolean",
            "description": "⚖️ Restrict to videos published under a Creative Commons licence — useful when you need reusable footage. Verified: 0 of 8 IDs matched an unfiltered search. Video results only.",
            "default": false
          },
          "onlyLiveNow": {
            "title": "🔴 Only streams that are live right now",
            "type": "boolean",
            "description": "🔴 Restrict to streams currently broadcasting. Verified: 8 of 8 returned rows had liveStatus = is_live. Video results only.",
            "default": false
          },
          "detailLevel": {
            "title": "💸 Extraction depth",
            "enum": [
              "full",
              "fast"
            ],
            "type": "string",
            "description": "🐢 « Full » opens every result's own page: adds likes, comment count, subscriber count, tags, full description, exact publish timestamp, category and language. It only returns data through a RESIDENTIAL proxy and costs about 587 KB per row. ⚡ « Fast » reads the search page only: title, URL, rank, channel, view count, duration, verification badge — about 2 KB per row, roughly 277× cheaper, and it works without a proxy. Default is Full, which matches the previous behaviour of this scraper.",
            "default": "full"
          },
          "enrichPlaylistRows": {
            "title": "📂 Look up playlist size & owner",
            "type": "boolean",
            "description": "📂 Playlist search results carry only a title and a link. Turn this on to make one extra cheap request per playlist (~2 KB) that fills in the playlist's video count and its owning channel. Ignored when you are not searching for playlists.",
            "default": true
          },
          "dropDuplicateIds": {
            "title": "🧹 Drop duplicate results",
            "type": "boolean",
            "description": "🧹 YouTube repeats results across deep result pages (5 duplicates were measured in 426 rows). Leave on to keep one row per ID so you are not charged twice for the same video.",
            "default": true
          },
          "proxyConfiguration": {
            "title": "🌐 Proxy",
            "type": "object",
            "description": "🌐 Leave empty to run on the platform's own IP, which is enough for `Extraction depth = Fast`. ⚠️ Full extraction is bot-walled on datacenter IPs (measured: 0 rows and a « Sign in to confirm you're not a bot » page), so a Full run with no proxy starts on RESIDENTIAL, and a Full run on your own proxy escalates to RESIDENTIAL if YouTube blocks it. Every escalation is written to the log."
          },
          "verboseLogs": {
            "title": "🐛 Verbose logging",
            "type": "boolean",
            "description": "🐛 Log every yt-dlp call, the exact search URL including the sp= filter, and each proxy step. Useful for confirming a filter really was applied. Legacy key `debug` is still accepted.",
            "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}