Конструктор отчетов и дашбордов

Методы для построения аналитических отчётов — те же отчёты, что вы видите в личном кабинете в разделе «Конструктор отчётов», но через API. Удобно, если вы хотите получать графики и таблицы по своим данным в собственной системе (внутренней аналитике, дашборде, чат-боте с отчётами и т.д.) без захода в личный кабинет.

Методы конструктора отчётов доступны только на тарифе Premium.

Как это работает вкратце

Отчёт строится по событиям, которые вы отправляете в Graspil (см. Список событий). Чтобы понять, какие события и поля доступны для отчёта по вашему боту, используйте методы events, event-fields и utm-labels — они подсказывают, что можно подставить в фильтры и отчёт.
Сам отчёт описывается одним JSON-объектом report_config — в нём указано, что считать (какое событие, какая агрегация), как фильтровать и как группировать. Ниже подробно расписан его формат — это тот же формат, что использует визуальный конструктор отчётов в личном кабинете.
Прежде чем сохранять отчёт, его можно «прогнать» вхолостую методом preview — посмотреть первые строки результата и убедиться, что всё посчиталось так, как вы хотели.
Когда отчёт готов — сохраните его методом save. Сохранённые отчёты можно получить списком через list.

Авторизация

Если ваш API-ключ привязан к одному боту (обычный ключ из раздела «Мои боты» — см. Авторизацию) — ничего дополнительно указывать не нужно, все методы применяются к этому боту.

Если вы используете ключ из раздела «API-ключи», выданный сразу на несколько ботов или на все ваши боты, в каждом запросе нужно явно указать, какого бота он касается — заголовком Resource-Key либо полем (для POST) или параметром (для GET) resource_key. Значение — публичный ключ бота: часть до двоеточия в API-ключе бота, который вы видите в разделе «Мои боты» рядом с иконкой ключа (формат ключ_бота:api_key).

Методы save и list работают только с пользовательским ключом из раздела «API-ключи» — обычный ключ одного бота для них не подходит.

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

Успешный ответ:

{ "ok": true, "data": { ... } }

Ответ с ошибкой:

{ "ok": false, "error": "...", "error_code": 400 }

Конфигурация отчёта (`report_config`)

Это главный объект, который описывает отчёт. Его передают в методы preview и save, и его же возвращают сохранённые отчёты. Состоит из двух частей: source_request (что и как считать) и settings (период):

{
  "source_request": {
    "type": "trends",
    "type_chart": "line",
    "requests": [ ... ],
    "filters": null,
    "separators": [ ... ]
  },
  "settings": {
    "params": {
      ":date_from": "2026-01-01 00:00:00",
      ":date_to": "2026-01-31 23:59:59"
    }
  }
}

Поле

Описание

source_request

Что и как считать — тип отчёта (type / type_chart), события, фильтры, группировки. Описано ниже

settings.params

Период, за который строится отчёт. Ресурс (бот) подставляется автоматически по вашему ключу — указывать :resource_key самостоятельно не нужно

Параметр settings.params

Тип

Обязательный

Описание

:date_from

string

да

Начало периода, формат YYYY-MM-DD HH:MM:SS

:date_to

string

да

Конец периода, формат YYYY-MM-DD HH:MM:SS

Типы отчётов (`source_request.type` / `type_chart`)

type

type_chart

Что показывает

Когда использовать

trends

line

Динамику показателя по дням — график «событие/пользователи во времени»

Самый частый тип: «сколько событий/пользователей было каждый день»

trends

table

То же самое, но в виде таблицы, а не графика. У таблицы более короткий набор значений agr — см. ниже

Когда нужны точные числа по дням, а не картинка

list

Список сырых строк из таблицы событий (или другой таблицы), без агрегации

Когда нужен список конкретных событий, а не сводная цифра — например, журнал действий

funnels

Воронку: сколько пользователей прошли цепочку событий шаг за шагом

«Сколько из тех, кто открыл карточку товара, дошли до оплаты»

retention

Ретеншен: вернулись ли пользователи и сделали повторное действие через N дней

«Сколько пользователей, оплативших один раз, оплатили снова через неделю»

Дальше в зависимости от type заполняются разные поля source_request — они описаны в соответствующих разделах ниже.

Тренды и таблицы (`type: "trends"`)

Поле

Тип

Обязательный

Описание

requests

array

да

Один или несколько показателей на одном графике/таблице — см. «Показатель (requests)» ниже

filters

array|null

нет

Общий фильтр, применяется ко всем показателям сразу — см. «Фильтры» ниже

separators

array

нет

Разбивка показателя на несколько линий/строк по какому-то полю — см. «Разбивка (separators)» ниже

Показатель (`requests`)

Каждый элемент массива requests — это один показатель (одна линия на графике/строка в таблице):

{
  "type": "trend",
  "event_id": 5,
  "event_name": "purchase",
  "label": "Покупки",
  "agr": "total",
  "filters": null
}

Поле

Тип

Обязательный

Описание

type

string

да

Всегда "trend"

event_id

int|null

нет

ID события, которое считаем (см. метод events ниже). null — считать вообще все события

event_name

string

да

Название события — просто для удобства чтения, на расчёт не влияет

label

string

нет

Подпись показателя, которая будет в результате (например, название линии на графике)

agr

string

да

Как агрегировать — см. таблицу ниже

filters

array|null

нет

Фильтр именно для этого показателя (в дополнение к общему source_request.filters)

Агрегации (`agr`)

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

type_chart: "table":

Значение

Что считает

total

Общее количество событий

total_uniq

Количество уникальных пользователей, у которых было событие

avg

Среднее количество событий на одного пользователя

min

Минимальное количество событий на одного пользователя

max

Максимальное количество событий на одного пользователя

median

Медианное количество событий на одного пользователя

type_chart: "line", "bar", "area", "pie" и т.д. (любой график):

Значение

Что считает

total

Общее количество событий

total_uniq_user_id

Количество уникальных пользователей, у которых было событие

total_uniq_session_id

Количество уникальных сессий с этим событием

total_uniq_app_session_id

Количество уникальных сессий в Mini App с этим событием

avg_user_id

Среднее количество событий на одного пользователя

min_user_id

Минимальное количество событий на одного пользователя

max_user_id

Максимальное количество событий на одного пользователя

median_user_id

Медианное количество событий на одного пользователя

property_sum

Сумма числового поля события (agr_field) — например, сумма продаж

property_avg

Среднее значение числового поля события

property_min

Минимальное значение числового поля события

property_max

Максимальное значение числового поля события

property_median

Медианное значение числового поля события

Не смешивайте эти два набора. Запрос с type_chart: "table" и agr: "total_uniq_user_id" вернёт ошибку Unsupported aggregation. Для таблиц используйте короткую форму (total_uniq).

Для агрегаций property_* дополнительно обязателен параметр agr_field — какое поле агрегировать. Доступны два значения:

events.value_int — «сырое» значение как оно было отправлено в value_num, без перевода в обычные единицы и без конвертации валют. Для денежных событий это минимальные единицы валюты (например, копейки для RUB)
events.value_amount — то же значение, но переведённое в обычные единицы (рубли вместо копеек) и сконвертированное по курсу в валюту, установленную в профиле владельца ключа

Если считаете деньги (сумму продаж, выручку и т.п.) — используйте agr_field: "events.value_amount". С events.value_int итоговая сумма для денежных событий обычно будет казаться завышенной в 100 раз (или больше, если единица события — не копейка/цент).

Пример: сумма продаж по дням, в валюте профиля:

{ "type": "trend", "event_id": 5, "event_name": "purchase", "label": "Выручка", "agr": "property_sum", "agr_field": "events.value_amount" }

Фильтры

Фильтры сужают набор событий, которые попадают в расчёт. Указываются как вложенный массив [оператор, ...аргументы] — в том же стиле, что и фильтры аудитории в API рассылок, только поля берутся из таблицы событий (узнать доступные поля — метод event-fields ниже).

Логика: ["and", условие1, условие2, ...], ["or", ...]
Сравнение: ["=", "поле", значение], ["!=", ...], [">", ...], ["<", ...], [">=", ...], ["<=", ...]
Список значений: ["in", "поле", [значение1, значение2, ...]]
Диапазон: ["between", "поле", от, до]

Пример: только покупки на сумму от 1000:

[">=", "events.value_int", 1000]

Одно условие — это плоский массив [оператор, поле, значение]. Не оборачивайте его в дополнительный массив ([[">=", "events.value_int", 1000]] — неверно, API вернёт ошибку "expected a single condition, got a nested array"). Для нескольких условий явно комбинируйте их через ["and", ...] / ["or", ...] — просто список условий без "and"/"or" тоже невалиден.

Период (:date_from/:date_to) и ваш бот подставляются в фильтр автоматически — добавлять их вручную не нужно.

Разбивка (`separators`)

Разбивка показывает один и тот же показатель отдельно по каждому значению выбранного поля — например, отдельная линия на графике для каждого значения кастомного свойства события.

"separators": [
  { "property": "events.properties.plan_name" }
]

Можно указать сразу несколько separators — тогда разбивка будет по комбинации значений всех полей.

Элементы separators — это объекты с полем property из фиксированного списка (events.*-колонки, либо любое поле с префиксом events.properties.* / user.* / user.custom_fields.*). Голая строка вроде "utm_source" невалидна и вернёт ошибку Wrong separator property.

Для разбивки по UTM-source/medium/campaign не используйте separators — значения UTM не выведены как обычные поля events.properties.*, они лежат за внутренними id-колонками (events.f_param_id_*), которые обрабатывает отдельный UTM-механизм отчётов. Используйте type_chart: "utm_trends" / "utm_table" — см. "Разбивка по UTM" ниже, именно это использует визуальный конструктор отчётов для UTM-разбивок.

Разбивка по UTM (`type_chart: "utm_trends"` / `"utm_table"`)

Отдельный тип отчёта для разбивки показателя по UTM-метке (source/medium/campaign) без выбора конкретных значений метки заранее — например, «продажи по дням в разрезе UTM-метки».

type_chart

Что показывает

utm_trends

График во времени, одна линия на каждую комбинацию UTM (аналог line)

utm_table

Плоская сводная таблица, одна строка на каждую комбинацию UTM, без разбивки по времени (аналог table)

{
  "source_request": {
    "type": "trends",
    "type_chart": "utm_trends",
    "requests": [
      { "type": "trend", "event_id": 28, "event_name": "Sale", "label": "",
        "agr": "property_sum", "agr_field": "events.value_amount", "filters": [] }
    ],
    "filters": null,
    "separators": [],
    "granularity": "day",
    "breakdown_limit": 25,
    "row_limit": 100
  },
  "settings": { "params": { ":date_from": "2026-06-01 00:00:00", ":date_to": "2026-06-29 23:59:59" } }
}

Поле

Тип

Обязательно

Описание

requests

array

да

Тот же формат, что и в обычных trends. Для property_*-агрегаций поле agr_field обязательно (как и в обычных trends): для сумм денег — agr_field: "events.value_amount" (с конвертацией валют). Автоматической подстановки поля больше нет — без agr_field запрос вернёт ошибку

breakdown_limit

int

нет

Максимум комбинаций UTM в ответе (5–500, по умолчанию 25) — какие именно комбинации попадут в разбивку, выбирается автоматически, указывать их не нужно

row_limit

int

нет

Максимум строк в ответе (1–5000, по умолчанию 100)

granularity

string

нет

Шаг бакетов для utm_trends, например day — для utm_table игнорируется

Если нужно отфильтровать по ОДНОМУ конкретному известному значению UTM (например, «продажи с utm_source=vk»), а не разбить по всем сразу — это обычное условие filters в отчёте trends/line, а не разбивка по UTM. Сначала уточните точное значение через метод utm-labels.

Список событий (`type: "list"`)

Возвращает сырые строки без агрегации — например, журнал последних событий.

Поле

Тип

Обязательный

Описание

table

string

да

Таблица-источник, обычно "events"

columns

array

да

Какие поля вернуть, например ["events.date", "events.user_id", "events.event_type_id"]

filters

array|null

нет

Фильтр — формат как в разделе «Фильтры» выше

order

object

нет

Сортировка, например { "events.date": "desc" }

limit

int

нет

Сколько строк вернуть, по умолчанию 50, максимум 1000

offset

int

нет

Смещение для постраничной выгрузки

Воронка (`type: "funnels"`)

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

Поле

Тип

Обязательный

Описание

requests

array

да

Шаги воронки по порядку — каждый элемент в том же формате, что «Показатель» выше (поле agr не важно, обычно total)

funnel_window

int

нет

Сколько времени даётся пользователю, чтобы пройти всю воронку

funnel_window_unit

string

нет

Единица для funnel_window: second, minute, hour, day, week, month. По умолчанию — 14 дней

funnel_order_type

string

нет

Насколько строго проверяется порядок шагов — см. таблицу ниже

separators

array

нет

Разбивка воронки по полю, как в трендах

funnel_order_type

Поведение

ordered

Шаги должны идти в указанном порядке, между ними допускаются любые другие действия

strict

Следующий шаг должен случиться сразу после предыдущего, без посторонних действий между ними

unordered

Порядок шагов не важен

Пример (показано содержимое source_request; оберните его в report_config вместе с settings — см. раздел «Конфигурация отчёта»), воронка «посмотрел товар → оплатил» с окном 30 дней:

{
  "type": "funnels",
  "type_chart": "funnels",
  "requests": [
    { "type": "trend", "event_id": 1, "event_name": "view_item", "agr": "total" },
    { "type": "trend", "event_id": 5, "event_name": "purchase", "agr": "total" }
  ],
  "funnel_window": 30,
  "funnel_window_unit": "day",
  "funnel_order_type": "ordered"
}

Ретеншен (`type: "retention"`)

Показывает, какая доля пользователей, выполнивших стартовое действие, вернулась и выполнила его (или другое) повторно через определённое количество дней/недель.

Поле

Тип

Обязательный

Описание

target_entity

object

да

Стартовое событие — кого считаем «вошедшим в когорту». Формат: { "type": "event", "event_id": ..., "event_name": "..." }

returning_entity

object

да

Событие, которое считается «возвращением». Тот же формат, что target_entity

retention_total_intervals

int

нет

Сколько интервалов показать, по умолчанию 8

granularity

string

нет

Шаг интервала — day или week

retention_type

string

нет

Логика отбора в когорту — см. таблицу ниже

separators

array

нет

Разбивка ретеншена по полю

retention_type

Логика

retention_first_time

В когорту попадает первое за период действие, подходящее по условию (по умолчанию)

retention_first_time_ever

В когорту попадает пользователь только если его самое первое действие вообще (без учёта периода) подходит по условию

retention_recurring

Пользователь может попадать в несколько когорт — за каждый интервал, в котором выполнил стартовое действие

Пример (показано содержимое source_request; оберните его в полный report_config — см. раздел «Конфигурация отчёта»), вернулись ли пользователи, открывшие бота, чтобы открыть его снова через 8 дней:

{
  "type": "retention",
  "type_chart": "retention",
  "granularity": "day",
  "retention_total_intervals": 8,
  "target_entity": { "type": "event", "event_id": 1, "event_name": "open_bot" },
  "returning_entity": { "type": "event", "event_id": 1, "event_name": "open_bot" }
}

Методы

GET /v1/reports/resources

Возвращает бота (или ботов), к которым у вашего ключа есть доступ. Полезно для ключей из раздела «API-ключи», выданных сразу на несколько ботов — чтобы узнать, какие resource_key доступны и какие значения подставлять в остальные методы.

Resource-Key для этого метода указывать не нужно.

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

GET /v1/reports/resources
Api-Key: YOUR_API_KEY

Ответ

{
  "ok": true,
  "data": [
    { "key": "abc123...", "name": "Мой бот", "type": 1 }
  ]
}

GET /v1/reports/events

Возвращает список событий, которые можно использовать в отчёте по конкретному боту (поле event_id в показателях).

Параметры

Параметр

Тип

Обязательный

Описание

resource_key

string

только для ключей с доступом к нескольким ботам

См. раздел «Авторизация» выше

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

GET /v1/reports/events
Api-Key: YOUR_API_KEY

Ответ

{
  "ok": true,
  "data": [
    { "id": 5, "name": "purchase", "category": "Покупки", "is_global": false }
  ]
}

GET /v1/reports/event-fields

Возвращает список полей события, которые можно использовать в фильтрах (filters). Набор полей фиксирован и не зависит от бота или конкретного события.

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

GET /v1/reports/event-fields
Api-Key: YOUR_API_KEY

Ответ

{
  "ok": true,
  "data": [
    { "field": "events.value_int", "type": "number", "label": "Числовое значение" }
  ]
}

type — одно из: number, string, date.

GET /v1/reports/utm-labels

Возвращает UTM-метки (источники, каналы, кампании), которые реально встречались у вашего бота — удобно, чтобы предложить пользователю выбор в фильтре, а не угадывать значения.

Параметры

Параметр

Тип

Обязательный

Описание

resource_key

string

только для ключей с доступом к нескольким ботам

См. раздел «Авторизация» выше

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

GET /v1/reports/utm-labels
Api-Key: YOUR_API_KEY

Ответ

{
  "ok": true,
  "data": {
    "sources": ["telegram", "vk"],
    "mediums": ["cpc", "social"],
    "campaigns": ["spring_sale"]
  }
}

POST /v1/reports/preview

Прогоняет отчёт без сохранения и возвращает первые 10 строк результата — удобно, чтобы проверить, что отчёт настроен правильно, прежде чем сохранять его.

Параметры

Параметр

Тип

Обязательный

Описание

resource_key

string

только для ключей с доступом к нескольким ботам

См. раздел «Авторизация» выше

report_config

object

да

Конфигурация отчёта — см. раздел выше

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

POST /v1/reports/preview
Api-Key: YOUR_API_KEY
Content-Type: application/json

{
  "report_config": {
    "source_request": {
      "type": "trends",
      "type_chart": "line",
      "requests": [
        { "type": "trend", "event_id": 5, "event_name": "purchase", "label": "Покупки", "agr": "total" }
      ]
    },
    "settings": {
      "params": { ":date_from": "2026-06-01 00:00:00", ":date_to": "2026-06-29 23:59:59" }
    }
  }
}

Ответ

{
  "ok": true,
  "data": {
    "rows": [
      { "date": ["2026-06-01", "2026-06-02"], "total": [12, 18] }
    ],
    "total_estimate": 2
  }
}

В превью пока не поддерживаются когортные фильтры (in_cohort/not_in_cohort).

POST /v1/reports/save

Сохраняет отчёт — после этого он появляется в личном кабинете в разделе «Конструктор отчётов» и доступен через метод list.

Работает только с пользовательским ключом из раздела «API-ключи» — у сохранённого отчёта должен быть владелец.

Параметры

Параметр

Тип

Обязательный

Описание

resource_key

string

только для ключей с доступом к нескольким ботам

См. раздел «Авторизация» выше

name

string

да

Название отчёта

report_config

object

да

Конфигурация отчёта — см. раздел выше

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

POST /v1/reports/save
Api-Key: YOUR_API_KEY
Content-Type: application/json

{
  "name": "Покупки по дням",
  "report_config": {
    "source_request": {
      "type": "trends",
      "type_chart": "line",
      "requests": [
        { "type": "trend", "event_id": 5, "event_name": "purchase", "label": "Покупки", "agr": "total" }
      ]
    },
    "settings": {
      "params": { ":date_from": "2026-06-01 00:00:00", ":date_to": "2026-06-29 23:59:59" }
    }
  }
}

Ответ

{ "ok": true, "data": { "uuid": "f1b2c3d4-..." } }

uuid — идентификатор сохранённого отчёта, по нему отчёт можно найти в списке (list) или открыть в личном кабинете.

GET /v1/reports/list

Возвращает ранее сохранённые отчёты.

Работает только с пользовательским ключом из раздела «API-ключи».

Параметры

Параметр

Тип

Обязательный

Описание

resource_key

string

нет

Если указан — вернутся только отчёты этого бота. Если не указан — отчёты по всем доступным ключу ботам

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

GET /v1/reports/list
Api-Key: YOUR_API_KEY

Ответ

{
  "ok": true,
  "data": [
    { "uuid": "f1b2c3d4-...", "name": "Покупки по дням", "created_at": "2026-06-29 12:00:00", "resource_key": "abc123..." }
  ]
}

Возможные ошибки

Код

Когда возникает

400

Не передан обязательный параметр (например, report_config или :date_from/:date_to), либо параметр неверного формата

401

API-ключ не передан или недействителен

403

Метод недоступен на вашем тарифе (требуется Premium), ресурс недоступен этому ключу, либо save/list вызваны не пользовательским ключом

404

Бот по указанному resource_key не найден

500 / 502

Внутренняя ошибка сервера — повторите запрос позже

Пример ошибки:

{ "ok": false, "error": { "errors": "Premium tariff required" }, "error_code": 403 }

ПредыдущаяАвтоматизации

СледующаяMCP-сервер (AI-агенты)

Последнее обновление 1 месяц назад

Как это работает вкратце

Авторизация

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

Конфигурация отчёта (report_config)

Типы отчётов (source_request.type / type_chart)

Тренды и таблицы (type: "trends")

Показатель (requests)

Агрегации (agr)

Фильтры

Разбивка (separators)

Разбивка по UTM (type_chart: "utm_trends" / "utm_table")

Список событий (type: "list")

Воронка (type: "funnels")

Ретеншен (type: "retention")

Методы

GET /v1/reports/resources

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

Ответ

GET /v1/reports/events

Параметры

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

Ответ

GET /v1/reports/event-fields

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

Ответ

GET /v1/reports/utm-labels

Параметры

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

Ответ

POST /v1/reports/preview

Параметры

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

Ответ

POST /v1/reports/save

Параметры

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

Ответ

GET /v1/reports/list

Параметры

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

Ответ

Возможные ошибки

Конфигурация отчёта (`report_config`)

Типы отчётов (`source_request.type` / `type_chart`)

Тренды и таблицы (`type: "trends"`)

Показатель (`requests`)

Агрегации (`agr`)

Разбивка (`separators`)

Разбивка по UTM (`type_chart: "utm_trends"` / `"utm_table"`)

Список событий (`type: "list"`)

Воронка (`type: "funnels"`)

Ретеншен (`type: "retention"`)