{
  "openapi": "3.0.1",
  "info": {
    "title": "Yandex SERP Scraper — Rank Tracking, Ads & Regions",
    "description": "Yandex search results scraper: organic rankings, ads and result blocks for yandex.ru, .com.tr, .com, .kz, .by, .uz in any region. Bulk, no captchas.",
    "version": "1.0",
    "x-build-id": "IhDbPPUbUsU0wiIVJ"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/cheapapi~yandex-serp-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-cheapapi-yandex-serp-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/cheapapi~yandex-serp-scraper/runs": {
      "post": {
        "operationId": "runs-sync-cheapapi-yandex-serp-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/cheapapi~yandex-serp-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-cheapapi-yandex-serp-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",
        "required": [
          "queries"
        ],
        "properties": {
          "queries": {
            "title": "Search terms",
            "minItems": 1,
            "maxItems": 10000,
            "type": "array",
            "description": "What you would type into Yandex, one per line (up to 400 characters / 40 words each). Up to 10,000 searches per run (search terms × <b>Several regions</b>); duplicates are removed.<br>• Yandex search operators work: <code>site:</code>, <code>\"exact phrase\"</code>, <code>-word</code>, <code>!word</code>.<br>• Own region for one term: <code>купить диван | Kazan</code> (only when the part after <code>|</code> is a known place; for a literal Yandex OR like <code>a | Moscow</code>, set the region in the Region field instead).<br>• Or paste a Yandex results-page URL (<code>https://yandex.ru/search/?text=…&amp;lr=213</code>): its search term, domain and region are used.",
            "items": {
              "type": "string"
            }
          },
          "searchDomain": {
            "title": "Yandex domain",
            "enum": [
              "yandex.ru",
              "yandex.com.tr",
              "yandex.com",
              "yandex.kz",
              "yandex.by",
              "yandex.uz"
            ],
            "type": "string",
            "description": "Which Yandex search to use. Each domain has its own index and rankings. For yandex.com, .kz, .by and .uz, clear <b>Region</b> (they use <b>Location by IP address</b>).",
            "default": "yandex.ru"
          },
          "region": {
            "title": "Region (city or country)",
            "type": "string",
            "description": "Where the search is made from — rankings differ a lot between cities.<br>• A city or country name in English or Russian (\"Moscow\", \"Kazan\", \"Istanbul\", \"Москва\") or a Yandex region ID (213 = Moscow).<br>• Works on yandex.ru and yandex.com.tr.<br>• Empty = the whole country (Russia or Turkey).<br>• One term can have its own region: <code>term | Kazan</code>.<br>• A name that exists in several places means the larger region; give the numeric ID to be exact.<br>• Clear this field for yandex.com, .kz, .by and .uz (they use <b>Location by IP address</b> instead)."
          },
          "maxResults": {
            "title": "Results per search term",
            "minimum": 1,
            "maximum": 250,
            "type": "integer",
            "description": "How many organic results to collect for each search term (1–250; Yandex shows at most 250). Organic results are charged per started group of 20 delivered results (20 results = 1 page, 100 results = 5 pages); the full results page per started group of 10.",
            "default": 20
          },
          "resultType": {
            "title": "Result type",
            "enum": [
              "organic",
              "fullPage"
            ],
            "type": "string",
            "description": "<b>Organic results</b>: the ranked organic results with title, URL, snippet passages, page date and language — the right choice for rank tracking. <b>Full results page</b>: everything the results page shows, in order — organic results (with sitelinks and shop ratings), ads, the Alice AI quick answer (AI overview) with sources, the knowledge panel, image/video/product blocks and related searches — for desktop or mobile, optionally with the page HTML.",
            "default": "organic"
          },
          "outputFormat": {
            "title": "Output format",
            "enum": [
              "results",
              "searches"
            ],
            "type": "string",
            "description": "<b>One row per result</b> is best for spreadsheets. <b>One row per search term</b> puts all results of a search term in one row (with tracked-domain positions), which is handy for rank tracking and APIs.",
            "default": "results"
          },
          "trackDomains": {
            "title": "Track domains",
            "type": "array",
            "description": "Your own or competitors' domains, e.g. <code>citilink.ru</code> or <code>trendyol.com</code> (subdomains included), or a section of a site, e.g. <code>example.com/blog</code> (only URLs under that path). Matching results get <code>isTracked: true</code>. Choose Output format “One row per search term” to also get each entry's position (or null when not found) in one row per search term. Free.",
            "items": {
              "type": "string"
            }
          },
          "trackedOnly": {
            "title": "Deliver only tracked-domain results",
            "type": "boolean",
            "description": "With <b>Track domains</b> and Output format “One row per result”: the dataset gets only the results of your tracked domains (all positions are still checked). The checked results pages are charged as usual — this only keeps your dataset small. Ignored unless Track domains is filled and Output format is “One row per result”.",
            "default": false
          },
          "excludeDomains": {
            "title": "Exclude domains",
            "type": "array",
            "description": "Domains (or site sections such as <code>example.com/forum</code>) whose results you do not want in the dataset, e.g. marketplaces. All positions are still checked and charged as usual and keep their real position numbers; only the matching rows are left out. With “One row per search term” they are left out of the nested lists (tracked-domain positions still count every result).",
            "items": {
              "type": "string"
            }
          },
          "compareWithPreviousRun": {
            "title": "Compare with the previous run",
            "type": "boolean",
            "description": "Rank tracking over time: remembers the positions of this run in a key-value store in your account (the <b>History store name</b>, default <code>yandex-serp-rank-history</code>) and adds <code>previousPosition</code>, <code>positionChange</code> (positive = moved up) and <code>isNew</code> to every organic result of the next run with the same search term and settings. Free; ideal with a daily schedule.",
            "default": false
          },
          "minPositionChange": {
            "title": "Only results that moved at least (places)",
            "minimum": 0,
            "maximum": 250,
            "type": "integer",
            "description": "With <b>Compare with the previous run</b> and “One row per result”: store only organic results whose position changed by at least this many places (up or down) or that are new — ideal for daily change alerts. 0 = store everything. All positions are still checked and charged as usual; the first run (nothing to compare with yet) stores everything. Ignored unless Compare with the previous run is on.",
            "default": 0
          },
          "onlyNewResults": {
            "title": "Only new results",
            "type": "boolean",
            "description": "Monitoring: deliver only organic results whose URL was not delivered for the same search term (and settings) in earlier runs — the first run delivers everything and remembers it (in the <b>History store name</b> store of your account, default <code>yandex-serp-rank-history</code>). You pay only for new results; when nothing is new, the small no-results fee ($0.0012) per processed request applies, because the search was really made (a 10-result term: $0.0012; a 250-result term: up to $0.0036 in organic mode or $0.006 with the full results page). Together with <b>Compare with the previous run</b>, the delivered new results also get their comparison fields, and the rank history still covers every result.",
            "default": false
          },
          "historyName": {
            "title": "History store name",
            "pattern": "^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$",
            "maxLength": 63,
            "type": "string",
            "description": "Name (lowercase letters, digits and hyphens) of the key-value store in your account that keeps the rank history for Compare / Only new results (default <code>yandex-serp-rank-history</code>). Use one name per project or client to keep their histories apart; delete the store to start over."
          },
          "aiAnswer": {
            "title": "AI answer (+$0.06 per search term)",
            "type": "boolean",
            "description": "Also get an AI answer written by Yandex search for each search term: the answer text (Markdown with [n] citation marks) and its sources. Yandex writes these answers in Russian, Kazakh and Uzbek, so this works on yandex.ru, .kz, .by and .uz. Costs $0.06 per search term (10× a results page on Free, 15× on Gold), charged also when Yandex declines to answer. Tip: if you only need Yandex's AI overview when it is shown, choose Result type “Full results page” instead — it includes the overview at no AI answer fee. Ignored on yandex.com and yandex.com.tr.",
            "default": false
          },
          "language": {
            "title": "Interface language",
            "enum": [
              "auto",
              "ru",
              "uk",
              "be",
              "kk",
              "tr",
              "en"
            ],
            "type": "string",
            "description": "Language of the Yandex interface, which slightly influences results. yandex.ru supports Russian, Ukrainian, Belarusian and Kazakh; yandex.com.tr supports Turkish; yandex.com supports English. Other combinations are ignored with a warning.",
            "default": "auto"
          },
          "regions": {
            "title": "Several regions (optional)",
            "type": "array",
            "description": "Search every search term in each of these regions (city or country names, or region IDs), e.g. <code>Moscow</code>, <code>Saint Petersburg</code>, <code>Kazan</code>. Replaces <b>Region</b> for plain search terms; each term × region is charged as its own search. yandex.ru and yandex.com.tr only. Search terms × regions must not exceed 10,000 searches per run.",
            "items": {
              "type": "string"
            }
          },
          "device": {
            "title": "Device (full results page only)",
            "enum": [
              "desktop",
              "mobile"
            ],
            "type": "string",
            "description": "Desktop or mobile results page (the mobile page shows ads and blocks in a different order). Applies to “Full results page”.",
            "default": "desktop"
          },
          "saveHtml": {
            "title": "Save the page HTML (full results page only)",
            "type": "boolean",
            "description": "“Full results page” only: also store the complete HTML of every results page in the run's key-value store; each row gets an <code>htmlUrl</code> link to it. Included in the price.",
            "default": false
          },
          "period": {
            "title": "Time period",
            "enum": [
              "any",
              "day",
              "twoWeeks",
              "month"
            ],
            "type": "string",
            "description": "Only return pages that were updated within this period, using Yandex's page date (pages without a date may be left out). Leave “Any time” for rank tracking.",
            "default": "any"
          },
          "sortBy": {
            "title": "Sort by",
            "enum": [
              "relevance",
              "newest",
              "oldest"
            ],
            "type": "string",
            "description": "Normal Yandex ranking, or sorted by page date. Use Relevance for rank tracking.",
            "default": "relevance"
          },
          "safeSearch": {
            "title": "Safe search",
            "enum": [
              "moderate",
              "strict",
              "off"
            ],
            "type": "string",
            "description": "Filtering of adult content in the results. Moderate is what most Yandex users see; Strict is the family filter; Off shows everything.",
            "default": "moderate"
          },
          "fixTypos": {
            "title": "Fix typos automatically",
            "type": "boolean",
            "description": "When on, Yandex silently searches for the corrected spelling of a misspelled term (the correction is returned in <code>correctedQuery</code>). Turn off to search exactly what you typed.",
            "default": true
          },
          "resultsPerDomain": {
            "title": "Results per website",
            "minimum": 1,
            "maximum": 3,
            "type": "integer",
            "description": "1 = one result per position, exactly like the normal results page. 2–3 = also show up to 2–3 pages of the same website under its position (<code>domainGroupPosition</code>), which Yandex otherwise hides. Organic results only.",
            "default": 1
          },
          "snippetPassages": {
            "title": "Snippet passages",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "How many text passages to return in each organic result's snippet (1–5). Organic results only.",
            "default": 4
          },
          "locationIp": {
            "title": "Location by IP address",
            "type": "string",
            "description": "Optional: a public IPv4 or IPv6 address; results are localized as if the search was made from that address. Useful for yandex.com, .kz, .by and .uz, which do not support Region. Leave empty in most cases."
          },
          "maxWaitMinutes": {
            "title": "Maximum wait per search (minutes)",
            "minimum": 1,
            "maximum": 120,
            "type": "integer",
            "description": "How long to wait for one search before giving up. Searches normally finish in 2–10 seconds; the wait only matters when Yandex is overloaded.",
            "default": 15
          }
        }
      },
      "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}