API для работы с отчётами

Общая информация

Метод позволяет получать данные отчётов через API.

С помощью API доступны следующие типы данных:

домены, цитируемые в нейроответах;
URL страниц;
материалы;
разделы сайта;
поисковые запросы.

Данные могут быть получены в форматах JSON, CSV и TSV.

Получение доступа

Для начала работы с API необходимо обратиться в техническую поддержку через чат из авторизованного профиля.

После обработки обращения для вашего аккаунта будет создан API-токен, который необходимо использовать при выполнении запросов.

Endpoint

GET https://ai.dataforce.io/public-api/reporting/spaces/{space_id}/reports/neuro

Авторизация

Во всех запросах необходимо передавать API-токен в заголовке:

Authorization: Bearer <token>

Общие параметры запроса

periods	string	Период выборки в формате `YYYY-MM-DD:YYYY-MM-DD`
dimensions	string	Измерения отчёта
metrics	string	Метрики отчёта
order_by	string	Поле сортировки
filters	string	Набор фильтров
format	string	Формат ответа: `JSON`, `TSV`, `CSV`
marker	string	Маркер для постраничной навигации
with_totals	integer	`1` — вернуть итоговые значения
offset	integer	Смещение выборки
limit	integer	Ограничение количества записей

Доступные измерения и метрики зависят от типа отчёта.

Фильтры

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

Несколько фильтров передаются через символ ;.

Пример:

project_id<in>1;serp_source=yandex

Операторы фильтрации

Равно

serp_source=yandex

Входит в список значений

project_id<in>1

Для передачи нескольких значений используется разделитель |.

Пример:

serp_regions<in>213|1011969

Доступные фильтры

project_id	Идентификатор проекта
serp_source	Поисковая система
serp_regions	Регион поиска
serp_device	Тип устройства (`mobile`, `desktop`)
external_url_period	Период для URL-отчёта

Пример:

external_url_period=2026-04-28:2026-05-27

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

JSON	JSON-ответ с поддержкой итоговых значений (`totals`)
TSV	Формат табличных данных с разделителем табуляции
CSV	Формат табличных данных с разделителем запятая, точка с запятой

Доступные отчёты

Цитируемые сайты

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

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

GET https://ai.dataforce.io/public-api/reporting/spaces/{space_id}/reports/neuro
?periods=2026-04-28:2026-05-27
&dimensions=domain
&metrics=source_count,count_uniq_neuro,prc_count_uniq_neuro,frequency,prc_frequency
&order_by=source_count
&filters=project_id<in>1;serp_source=yandex;serp_regions<in>213|1011969;serp_device=mobile
&format=JSON
&with_totals=1
&offset=0
&limit=100000

Dimensions: domain

Metrics

source_count	Количество источников
count_uniq_neuro	Количество уникальных ответов Neuro
prc_count_uniq_neuro	Доля уникальных ответов Neuro, %
frequency	Частотность
prc_frequency	Доля частотности, %

Цитируемые страницы

Позволяет получать данные в разрезе конкретных URL, которые цитируются в нейроответах.

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

GET https://ai.dataforce.io/public-api/reporting/spaces/{space_id}/reports/neuro
?periods=2026-04-28:2026-05-27
&dimensions=url
&metrics=frequency,avg_position,count_articles
&order_by=frequency
&filters=external_url_period=2026-04-28:2026-05-27;project_id<in>1;serp_source=yandex;serp_regions<in>213|1011969;serp_device=mobile
&format=JSON
&marker=
&with_totals=1

Dimensions: url

Metrics

frequency	Частотность
avg_position	Средняя позиция
count_articles	Количество материалов

Особенности

Параметр filters должен содержать фильтр external_url_period.

Значение external_url_period должно соответствовать значению параметра periods.

Нейроответы

Позволяет получать данные по таблице отдельных нейроответов (статей)..

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

GET https://ai.dataforce.io/public-api/reporting/spaces/{space_id}/reports/neuro
?periods=2026-04-28:2026-05-27
&dimensions=article
&metrics=frequency,avg_position
&order_by=frequency
&filters=project_id<in>1;serp_source=yandex;serp_regions<in>213|1011969;serp_device=mobile
&format=JSON
&marker=
&with_totals=1

Dimensions: article

Metrics

frequency	Частотность
avg_position	Средняя позиция

Сегменты

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

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

GET https://ai.dataforce.io/public-api/reporting/spaces/{space_id}/reports/neuro
?periods=2026-04-28:2026-05-27
&dimensions=folder
&metrics=prc_frequency,source_count,count_uniq_neuro,prc_count_uniq_neuro_total,frequency
&order_by=prc_frequency
&filters=project_id=1;serp_source=yandex;serp_regions<in>213|1011969;serp_device=mobile
&format=JSON
&marker=
&with_totals=1

Dimensions: folder

Metrics

prc_frequency	Доля частотности, %
source_count	Количество источников
count_uniq_neuro	Количество уникальных ответов Neuro
prc_count_uniq_neuro_total	Доля уникальных ответов Neuro, %
frequency	Частотность

Особенности

Для параметра project_id используется оператор =.

Для остальных отчётов допускается использование оператора <in>.

Запросы

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

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

GET https://ai.dataforce.io/public-api/reporting/spaces/{space_id}/reports/neuro
?periods=2026-04-28:2026-05-27
&dimensions=query,has_neuro,has_articles,has_sources
&metrics=frequency,avg_position
&order_by=frequency
&filters=project_id<in>1;serp_source=yandex;serp_regions<in>213|1011969;serp_device=mobile
&format=JSON
&with_totals=1
&offset=0
&limit=10

Dimensions: query, has_neuro, has_articles, has_sources

Metrics

frequency	Частотность
avg_position	Средняя позиция

Справочники

Получение списка доступных измерений и метрик

Для получения списка доступных dimensions и metrics используйте запрос:

GET https://ai.dataforce.io/public-api/reporting/dictionaries

Справочники проекта

Для получения значений справочников используется следующий endpoint. Все словари привязаны к конкретному проекту (project_id).

GET https://ai.dataforce.io/public-api/reporting/projects/{project_id}/dictionaries/{dictionary}

Поисковые системы (serp_source)

GET https://ai.dataforce.io/public-api/reporting/projects/{project_id}/dictionaries/serp_source

Возвращает список доступных поисковых систем.

Регионы (serp_regions)

GET https://ai.dataforce.io/public-api/reporting/projects/{project_id}/dictionaries/serp_regions

Возвращает список доступных регионов.

Для фильтрации можно использовать несколько регионов через разделитель |.

Устройства (devices)

GET https://ai.dataforce.io/public-api/reporting/projects/{project_id}/dictionaries/devices

Возвращает список доступных устройств.

Запросы (queries)

GET https://ai.dataforce.io/public-api/reporting/projects/{project_id}/dictionaries/queries

Возвращает список запросов, доступных в проекте.

Категории (categories)

GET https://ai.dataforce.io/public-api/reporting/projects/{project_id}/dictionaries/categories

Возвращает список категорий (сегментов) — используется для экрана Сегменты