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

Источник: https://docs.dataforce.io/articles/api-reports

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

Метод позволяет получать данные отчётов через 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
```

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