{
  "openapi": "3.0.1",
  "info": {
    "title": "Youtube Search Rank Tracker",
    "description": "YouTube Search Results Scraper (Rank Tracker) captures YouTube SERP rankings for keywords and outputs rank (1..N) with video/channel metadata. Supports pagination, region + language + device mode, optional Shorts inclusion, and stable snapshots for daily/weekly SEO + competitor tracking.",
    "version": "1.1",
    "x-build-id": "UcgZ9rRqBXXwwv9ny"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/coregent~youtube-search-rank-tracker/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-coregent-youtube-search-rank-tracker",
        "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/coregent~youtube-search-rank-tracker/runs": {
      "post": {
        "operationId": "runs-sync-coregent-youtube-search-rank-tracker",
        "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/coregent~youtube-search-rank-tracker/run-sync": {
      "post": {
        "operationId": "run-sync-coregent-youtube-search-rank-tracker",
        "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",
        "required": [
          "queries"
        ],
        "properties": {
          "queries": {
            "title": "Search Queries",
            "type": "array",
            "description": "Search keywords to track rankings for. Supports phrases (e.g., 'AI automation tools').",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "maxResultsPerQuery": {
            "title": "Max Results Per Query",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "Maximum number of results to return per query (1–500).",
            "default": 50
          },
          "maxPages": {
            "title": "Max Pages",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "Number of pages to paginate per query (1–10). Each page yields ~20 results.",
            "default": 1
          },
          "regionCode": {
            "title": "Region Code",
            "enum": [
              "US",
              "GB",
              "CA",
              "AU",
              "IN",
              "DE",
              "FR",
              "JP",
              "BR",
              "MX",
              "ES",
              "IT",
              "NL",
              "SE",
              "NO",
              "DK",
              "FI",
              "PL",
              "RU",
              "KR",
              "TW",
              "HK",
              "SG",
              "MY",
              "PH",
              "TH",
              "ID",
              "VN",
              "ZA",
              "NG",
              "EG",
              "AE",
              "SA",
              "TR",
              "IL",
              "AR",
              "CL",
              "CO",
              "PE",
              "NZ",
              "IE",
              "AT",
              "CH",
              "BE",
              "PT",
              "CZ",
              "RO",
              "HU",
              "GR",
              "UA"
            ],
            "type": "string",
            "description": "ISO-3166-1 alpha-2 country code used for YouTube's gl parameter. The code in brackets is the value stored — match it to the proxy country in the Proxy section for a true in-country rank snapshot (e.g. Nigeria (NG) here and Nigeria in the proxy country list). This alone only localizes the response; the proxy is what makes the request originate in-country.",
            "default": "US"
          },
          "language": {
            "title": "Language",
            "enum": [
              "en",
              "es",
              "fr",
              "de",
              "pt",
              "it",
              "nl",
              "ja",
              "ko",
              "zh",
              "ru",
              "ar",
              "hi",
              "tr",
              "pl",
              "sv",
              "no",
              "da",
              "fi",
              "th",
              "vi",
              "id"
            ],
            "type": "string",
            "description": "UI language code (BCP-47 simplified). Affects search result language.",
            "default": "en"
          },
          "includeShorts": {
            "title": "Include Shorts",
            "type": "boolean",
            "description": "Include YouTube Shorts results when present in search.",
            "default": true
          },
          "sortBy": {
            "title": "Sort By",
            "enum": [
              "relevance",
              "upload_date",
              "view_count",
              "rating"
            ],
            "type": "string",
            "description": "Sort order for search results.",
            "default": "relevance"
          },
          "targetVideoIds": {
            "title": "Target Videos",
            "maxItems": 50,
            "type": "array",
            "description": "Optional. The videos you are tracking — accepts 11-character video IDs or full YouTube URLs (watch, youtu.be, or shorts links). Matching results are flagged with isTarget in the dataset, and each query reports your target's rank in RUN_SUMMARY.json. If a target does not appear in the scraped results, a 'target_not_found' row is added so a drop-out is visible instead of silently missing — those rows are never charged.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "uploadDate": {
            "title": "Upload Date",
            "enum": [
              "any",
              "hour",
              "today",
              "week",
              "month",
              "year"
            ],
            "type": "string",
            "description": "Only include videos uploaded within this period. Applied by YouTube itself as part of the search, so rank positions stay accurate. YouTube supports these fixed periods only — arbitrary date ranges are not available in YouTube search.",
            "default": "any"
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "How requests reach YouTube. Region Code alone only sets YouTube's language/locale parameters — a proxy is what makes the request genuinely originate in-country. For a true in-country rank snapshot, select Apify Proxy with the RESIDENTIAL group and set the proxy country to the same country as Region Code. Datacenter IPs are frequently blocked by YouTube and do not produce country-accurate rankings. You can also supply your own proxies via Custom proxy URLs (HTTP/HTTPS only — SOCKS is not supported). All pages of a single keyword are pinned to one exit IP so a paginated snapshot stays internally consistent. Proxy usage is included in the per-result price at no extra charge.",
            "default": {
              "useApifyProxy": 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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}