{
  "openapi": "3.0.1",
  "info": {
    "title": "YouTube Search Scraper With Keyword Rank Tracking",
    "description": "Automate YouTube search scraping with this actor. Collect video results for any keyword including titles, URLs, channels, views, thumbnails, and publish dates for marketing research, SEO analysis, and content intelligence.",
    "version": "0.1",
    "x-build-id": "SdVhcMHSnPv3yepws"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/api-empire~youtube-search-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-api-empire-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/api-empire~youtube-search-scraper/runs": {
      "post": {
        "operationId": "runs-sync-api-empire-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/api-empire~youtube-search-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-api-empire-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": {
          "searchKeywords": {
            "title": "🔑 Keywords to track",
            "type": "array",
            "description": "One keyword per line. Each one is searched separately and ranked independently, so 5 keywords give you 5 rank verdicts per tracked channel. Example: « python tutorial », « learn python fast ». (The base actor's `queries` field is still accepted and takes priority if present.)",
            "items": {
              "type": "string"
            },
            "default": [
              "python tutorial"
            ]
          },
          "trackedChannels": {
            "title": "🎯 Channels to track",
            "type": "array",
            "description": "The channels whose ranking you care about — yours or a competitor's. Accepts « @handle », a « UC… » channel ID, or a full channel URL. Each one is resolved to its channel ID once so matching survives a channel rename. Leave empty to skip rank verdicts and get ranked results + share-of-results only.",
            "items": {
              "type": "string"
            }
          },
          "resultsPerKeyword": {
            "title": "📊 Results per keyword",
            "minimum": 1,
            "maximum": 2000,
            "type": "integer",
            "description": "How deep into the results to look for each keyword (1–2000). Rank tracking usually only needs the first page or two — 20 covers the visible slots. On the flat tier this is ~2 KB per row, so depth is cheap here. YouTube normally stops returning fresh results long before 2000. (Base field `maxResults` is accepted and wins if present.)",
            "default": 20
          },
          "rankingOrder": {
            "title": "↕️ Result order",
            "enum": [
              "relevance",
              "date",
              "viewCount",
              "rating"
            ],
            "type": "string",
            "description": "How YouTube orders the results before ranking is read. « Relevance » is YouTube's default and applies no ordering parameter at all.",
            "default": "relevance"
          },
          "publishedWithin": {
            "title": "📅 Published within",
            "enum": [
              "",
              "lastHour",
              "today",
              "thisWeek",
              "thisMonth",
              "thisYear"
            ],
            "type": "string",
            "description": "Only rank results published inside this window. YouTube only offers these coarse buckets — there is no exact date range on the search surface. Leave « Any time » for no date restriction.",
            "default": ""
          },
          "videoLength": {
            "title": "⏱️ Video length",
            "enum": [
              "",
              "short",
              "medium",
              "long"
            ],
            "type": "string",
            "description": "Restrict to Short (under 4 min), Medium (4–20 min) or Long (over 20 min). Useful for separating Shorts slots from long-form slots, which compete differently.",
            "default": ""
          },
          "resultKind": {
            "title": "📺 Result kind",
            "enum": [
              "video",
              "channel",
              "playlist",
              "movie"
            ],
            "type": "string",
            "description": "What kind of entity occupies the slots you want to track. « Video » is the normal choice and also strips the playlist rows YouTube blends into an unfiltered search. « Channel » and « Playlist » return channel and playlist entities with their own row type.",
            "default": "video"
          },
          "emitRankRows": {
            "title": "🏁 Emit a rank verdict per keyword",
            "type": "boolean",
            "description": "One « keyword_rank » row per keyword × tracked channel, carrying bestRank, every rank that channel holds for that keyword, and a ranked / not_ranked verdict. Turn off if you only want raw results.",
            "default": true
          },
          "slotOwnersPerKeyword": {
            "title": "🥇 Slot owners to report per keyword",
            "minimum": 0,
            "maximum": 50,
            "type": "integer",
            "description": "How many distinct channels ranking ABOVE your tracked channel to report for each keyword (0 turns this off). If the tracked channel does not rank at all, the top slot holders are reported instead, so you still see who owns the keyword. Deduplicated by channel — one row per competing channel, at its best position.",
            "default": 10
          },
          "lookupSubscriberCounts": {
            "title": "👥 Look up subscriber counts",
            "type": "boolean",
            "description": "Fetch each relevant channel's About page once to attach its subscriber count and country. The flat search tier does not carry subscriber counts, so this is one extra request per channel (deduplicated). If a lookup fails, the count is left null — never zero.",
            "default": true
          },
          "maxChannelLookups": {
            "title": "🔢 Max channel lookups",
            "minimum": 0,
            "maximum": 500,
            "type": "integer",
            "description": "Hard cap on About-page fetches for the whole run, shared between tracked channels and slot owners. Each fetch is roughly 1–2.5 MB. Channels beyond the cap keep a null subscriber count rather than a guessed one.",
            "default": 30
          },
          "dataDepth": {
            "title": "🧬 Data depth",
            "enum": [
              "rank",
              "full"
            ],
            "type": "string",
            "description": "« Rank » returns search position, title, channel, views, duration, verified status and the search snippet — everything rank tracking needs. « Full metadata » additionally fetches likes, comment counts, exact publish dates, tags and subscriber counts per video, at roughly 300x the proxy traffic per row.",
            "default": "rank"
          },
          "maxFullExtractionRows": {
            "title": "🧯 Max rows to extract at full depth",
            "minimum": 0,
            "maximum": 2000,
            "type": "integer",
            "description": "Spend cap that only applies when Data depth is « Full metadata ». Caps how many rows in the entire run get the expensive per-video extraction; everything beyond it keeps its rank columns and leaves the metadata columns null. 25 rows ≈ 15 MB of residential traffic.",
            "default": 25
          },
          "proxyConfiguration": {
            "title": "🌐 Proxy",
            "type": "object",
            "description": "Leave off to run searches on the container's own IP — the flat search tier works there, which is why this actor is cheap. Set a proxy here if you want searches routed through one; it will be honoured rather than silently replaced."
          },
          "verboseLogs": {
            "title": "🐛 Verbose logging",
            "type": "boolean",
            "description": "Log per-channel About lookups, response sizes and per-keyword byte counts. Useful for confirming what the run actually cost. (Base field `debug` is also 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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}