Инициализация выгрузки поисковых запросов

Позволяет создать задачу для формирования отчета по поисковым запросам.

Формат запроса

POST /v4/user/{user-id}/hosts/{host-id}/pro/serp/queries/download/

Параметр

Тип

Обязательно

Описание

user-id

int64

Да

ID пользователя. Необходим для вызова любых ресурсов API Яндекс Вебмастера. Чтобы получить его, используйте метод GET /v4/user.

host-id

host id (string)

Да

ID сайта. Чтобы получить его, используйте метод GET /v4/user/{user‑id}/hosts.

Заголовки запроса

Для запроса необходимо указать три HTTP-заголовка:

  1. Authorization

    Authorization: OAuth {ваш_токен}

  2. Accept

    Accept: application/json

  3. Content-Type

    Content-Type: application/json

Пример запроса

POST https://api.webmaster.yandex.net/v4/user/{user-id}/hosts/{host-id}/pro/serp/queries/download/

Формат тела запроса

{
  "dates": ["2025-09-10", "2025-09-20", "2025-09-30"],
  "paths": ["/blog", "/catalog", "/about"],
  "region_ids": [],
  "use_pro_tariff": "false"
}

Параметр

Тип

Обязательно

Описание

dates

string

Да

Список дат, по которым требуется выгрузка.

paths

string

Да

URL-адреса страниц сайта. Каждый элемент должен начинаться с /.

region_ids

integer

Нет

Список идентификаторов регионов. Если передать пустой массив — будет выгрузка по всем регионам.

use_pro_tariff

string

Да

Определяет, какой доступ использовать для выгрузки:

  • true — расширенный;
  • false — базовый.

Формат ответа

Пример

{
  "task_id": "2f1c5d3b-7d9b-4c3e-8a14-9d8b924a12ef",
  "free_quota_used": 10,
  "pro_quota_used": 0,
  "total_quota_used": 10,
  "free_quota_remaining": 90,
  "pro_quota_remaining": 1000
}

Параметр

Тип

Обязательно

Описание

task_id

string (UUID)

Да

Идентификатор созданной задачи.

free_quota_used

integer

Да

Сколько URL выгружено этим запросом в базовом доступе.

pro_quota_used

integer

Да

Сколько URL выгружено этим запросом в расширенном доступе.

total_quota_used

integer

Да

Общее число URL, которые выгрузил этот запрос.

free_quota_remaining

integer

Да

Остаток URL после запроса в базовом доступе.

pro_quota_remaining

integer

Да

Остаток URL после запроса в расширенном доступе.

Коды ответа

Чтобы посмотреть структуру ответа подробнее, нажмите на причину.

Код

Причина

Описание

200

OK

Успешно.

400

WRONG_REGIONS

Регионы некорректны.

{
  "code": "WRONG_REGIONS",
  "message": "Region ids must be positive"
}

400

EMPTY_PATHS

Пустые пути.

{
  "code": "EMPTY_PATHS",
  "message": "Paths cannot be empty"
}

400

EMPTY_DATES

Пустые даты.

{
  "code": "EMPTY_DATES",
  "message": "Dates cannot be empty"
}

400

SOME_DATES_ARE_UNAVAILABLE

Некоторые даты недоступны (слишком старые или еще не обработаны).

{
  "code": "SOME_DATES_ARE_UNAVAILABLE",
  "message": "Some dates are unavailable. Examples: [2024-01-01, 2024-01-02, 2024-01-03]",
  "unavailable_dates": ["2024-01-01", "2024-01-03"]
}

400

URLS_ARE_CORRUPTED

Некоторые переданные пути/URL некорректны.

{
  "code": "URLS_ARE_CORRUPTED",
  "message": "Some urls are corrupted or invalid for the specified host"
}

403

LIMITS_EXCEEDED

Превышены лимиты расширенного доступа.

{
  "code": "LIMITS_EXCEEDED",
  "message": "PRO feature limits exceeded"
}

413

PAYLOAD_TOO_LARGE

Превышен размер запроса по количеству дат и URL.

{
  "code": "PAYLOAD_TOO_LARGE",
  "message": "Amount of dates and urls is too large. Limit: 100",
  "limit": 100
}

Узнайте больше

OAuth-токен для доступа к API.

Указывает, что ответ должен быть в формате JSON.

Тип: int64. ID пользователя. Необходим для вызова любых ресурсов API Яндекс Вебмастера. Чтобы получить его, используйте метод GET /v4/user.

Указывает, что тело запроса должно быть в формате JSON.

Тип: host id (string). ID сайта. Чтобы получить его, используйте метод GET /v4/user/{user‑id}/hosts.

Тип: integer. Максимально допустимый суммарный размер (дат + URL).

Тип: string. Полный список недоступных дат.

Предыдущая
Доступные даты
Следующая
Получение статуса