Запросы к аналитике из CLI

SDK читает Аналитику Adapty прямо из терминала с помощью команд adapty analytics. Он возвращает те же данные, что отображаются в разделе Analytics дашборда, для одного приложения: графики — доход, MRR и другие, — конверсии, воронку, удержание, LTV и когорты установок.

Используйте это, чтобы дать AI-агенту доступ к живым данным вашего приложения, подтянуть график в скрипт или таблицу, или ответить на один вопрос без открытия дашборда.

Every analytics command is read-only and takes one app.

Перед началом работы

Тема analytics использует те же настройки установки и входа, что и остальная часть CLI. Если вы ещё не настроили это, выполните шаги 1 и 2 из руководства по быстрому старту. Для работы темы требуется версия CLI 0.10.0 или выше. Чтобы узнать свою версию, выполните adapty --version.

В отличие от API экспорта аналитики, CLI не требует секретного API-ключа. При входе через CLI вы получаете доступ ко всем приложениям, доступным вашему пользователю Adapty.

Каждая команда принимает UUID приложения в параметре --app. Чтобы найти его, выполните:

adapty apps list

Создайте запрос

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

Посмотрите, на какие вопросы может ответить аналитика приложения. Каталог содержит все графики с их единицами измерения, все конверсии, группировки и фильтры, которые принимает каждая команда, а также допустимые значения и настройки по умолчанию для каждого параметра:
```
adapty analytics catalog --app <app-id>
```
Названия графиков и конверсий, такие как revenue, mrr или trial-paid, берутся из этого списка. CLI не хранит собственного списка, поэтому графики, которые Adapty добавит позже, будут работать без обновления CLI.
Найдите значения фильтров. Пропустите этот шаг, если не используете фильтры. Например, чтобы получить список стран, по которым можно фильтровать:
```
adapty analytics values --app <app-id> --dimension country
```

Выполните команду для получения данных:

adapty analytics chart --app <app-id> --chart revenue \
  --date-from 2026-07-01 --date-to 2026-09-30 --group-by country

Ответ содержит одну строку для итога и по одной строке для каждой группы.

Примеры

MRR за текущий квартал в сравнении с предыдущим:

adapty analytics chart --app <app-id> --chart mrr \
  --date-from 2026-07-01 --date-to 2026-09-30 \
  --compare-from 2026-04-01 --compare-to 2026-06-30

Ежемесячная конверсия из пробного периода в платный в двух странах:

adapty analytics conversion --app <app-id> --conversion trial-paid \
  --date-from 2026-04-01 --date-to 2026-09-30 --granularity month --filter country=US,GB

Удержание по странам, отсчитываемое от пробного периода:

adapty analytics retention --app <app-id> --date-from 2026-07-01 --date-to 2026-09-30 \
  --group-by country --use-trial

LTV за 7, 30 и 90 дней, на основе выручки после комиссии и налогов, сохранённый в CSV-файл:

adapty analytics ltv --app <app-id> --date-from 2026-07-01 --date-to 2026-09-30 \
  --revenue-basis net --period-type days --renewal-days 7,30,90 --csv > ltv.csv

Еженедельные когорты установок на основе выручки после комиссии стора:

adapty analytics cohort --app <app-id> --date-from 2026-07-01 --date-to 2026-09-30 \
  --granularity week --revenue-basis proceeds

Выберите формат вывода

Каждая команда вывода данных печатает в одном из трёх форматов:

Вывод	Флаг	Для чего
Table	Нет	Чтение в терминале. Каждая таблица начинается с заголовка, в котором указаны название графика, период, часовой пояс и фильтры. Денежные значения отображаются с 2 знаками после запятой. Некоторые поля опущены, например причины оттока в воронке и прогнозы когорт — об этом сообщается строкой под таблицей.
JSON	`--json`	Скрипты и AI-агенты. Ответ API без изменений, со всеми полями.
CSV	`--csv`	Таблицы. Одна строка на группу, со всеми полями ответа. Сравниваемый период попадает в колонки `compare.*` той же строки.

Нельзя использовать --csv и --json одновременно.

В JSON общий итог — это первый элемент data.segments, а data.value — число за весь период. meta.query показывает выполненный запрос со всеми заполненными значениями по умолчанию и действующим часовым поясом.

Читаем результаты

Даты: --date-from и --date-to — это включительные дни в часовом поясе отчётности приложения. Чтобы читать дни в другом часовом поясе, передайте IANA-имя в --timezone, например Europe/Berlin. meta.query.timezone показывает применяемый часовой пояс.
Выручка: --revenue-basis задаёт, какие денежные значения использовать: gross (по умолчанию), proceeds (после комиссии стора) или net (после комиссии и налогов). Работает с ltv, cohort и графиками, отображающими деньги. В каталоге такие графики помечены как takes revenue_basis.
Пустые значения: пустое значение означает, что у Adapty нет данных, а не ноль. LTV-период, до которого когорта ещё не дошла, будет пустым, как и когорта, для которой нельзя построить прогноз. В выводе --json такие значения равны null. В таблице отображается —, в CSV ячейка остаётся пустой.
Строка итогов: ищите итог по is_total, а не по пустому key. key группы тоже может быть пустым — например, для группы пользователей без страны.
Ключи групп: key группы не всегда является значением, которое принимает --filter. Для фильтрации берите значения из analytics values.
Сравниваемые периоды: --compare-from и --compare-to поддерживаются только в chart и conversion. У сравниваемого периода есть собственные итог и группы, и в таблице он выводится как вторая таблица.
Числа атрибуции: не складывайте эти числа с числами из Attribution. Adapty вычисляет их по-разному.

CLI возвращает те же числа, что и дашборд, за двумя исключениями:

funnel применяет фильтр cancellation_reason, который дашборд в воронке игнорирует. Из-за этого фильтра цифры могут расходиться.
retention предлагает другой список группировок, чем дашборд. Берите список из каталога.

Лимиты

Каждая аналитическая команда принимает не более 2 запросов в секунду на приложение и не более 360 запросов в минуту суммарно. CLI никогда не повторяет запросы автоматически. При слишком высокой частоте запросов команда завершается с кодом 4. При использовании --json ошибка содержит поле retry_after_seconds: подождите указанное время, затем выполните команду снова.

Ошибки

Каждая ошибка завершается с кодом, который подсказывает, что нужно исправить:

Код выхода	Причина	Что делать
2	CLI отклонил входные данные до отправки запроса: недействительный UUID приложения, неправильный или перевёрнутый диапазон дат, сравниваемый период с одним незаданным концом, `--renewal-days` без `--period-type days`, `--filter` без `=` или `--csv` вместе с `--json`.	Исправьте флаг, указанный в сообщении.
3	Вы не вошли в систему или ваш пользователь Adapty не имеет доступа к приложению.	Войдите с помощью `adapty auth login`. Если вы уже вошли, найдите идентификатор приложения в `adapty apps list` — там отображаются только доступные вам приложения.
4	Adapty отклонил запрос: неизвестный график, конверсия, группировка, фильтр или часовой пояс; `--revenue-basis` для графика, не отображающего денежные данные; или превышение лимита запросов.	Исправьте название с помощью `adapty analytics catalog`. При использовании `--json` ошибка содержит код ошибки API. При превышении лимита запросов см. раздел Лимиты.

Справочник команд

Каждая команда для работы с данными принимает следующие флаги:

Флаг	Обязателен	Описание
`--app`	Да	UUID приложения из `adapty apps list`.
`--date-from`	Да	Первый день периода включительно в формате `YYYY-MM-DD`.
`--date-to`	Да	Последний день периода включительно. Не может быть раньше `--date-from`.
`--filter`	Нет	`dimension=value[,value]`. Оставляет данные, у которых измерение принимает одно из указанных значений. Повторите флаг для фильтрации по нескольким измерениям. Используйте `\,` для запятой внутри значения. Пустое значение — это тоже значение: `country=` оставляет данные без страны.
`--timezone`	Нет	Часовой пояс IANA для дней, например `Europe/Berlin`. Если не указан, используется часовой пояс приложения.
`--csv`	Нет	Выводит таблицу в формате CSV вместо обычной. Нельзя использовать вместе с `--json`.

Каждая команда добавляет к ним собственные флаги.

`analytics catalog`

Перечисляет, на какие вопросы может ответить аналитика приложения: каждая команда с её параметрами, группировками и фильтрами; каждый график с единицей измерения; каждая конверсия; каждый фильтр-измерение.

Флаг	Обязательный	Описание
`--app`	Да	UUID приложения из `adapty apps list`.

`analytics values`

Перечисляет значения, которые одно измерение фильтра принимает для приложения. Каждый value — это именно то, что принимает --filter <dimension>=<value>.

Флаг	Обязательный	Описание
`--app`	Да	UUID приложения из `adapty apps list`.
`--dimension`	Да	Измерение фильтра из `adapty analytics catalog`.

`analytics chart`

Читает один график: значение за весь период, его точки и группы.

Флаг	Обязательный	Описание
`--chart`	Да	Название графика из `adapty analytics catalog`, например `revenue` или `mrr`.
`--group-by`	Нет	Одна группировка для этого графика, из каталога.
`--granularity`	Нет	Длина одной точки: `day`, `week`, `month` (по умолчанию), `quarter` или `year`.
`--revenue-basis`	Нет	`gross` (по умолчанию), `proceeds` или `net`. Только для графиков с денежными значениями.
`--compare-from`	Нет	Первый день периода для сравнения. Требует `--compare-to`.
`--compare-to`	Нет	Последний день периода для сравнения. Требует `--compare-from`.

`analytics conversion`

Считывает одну конверсию: процентное значение и два числа, которые его образуют, для каждой точки и группы.

Флаг	Обязательный	Описание
`--conversion`	Да	Название конверсии из `adapty analytics catalog`, например `trial-paid` или `install-paid`.
`--group-by`	Нет	Одна группировка из каталога.
`--granularity`	Нет	Длина одной точки: `day` (по умолчанию), `week`, `month`, `quarter` или `year`.
`--compare-from`	Нет	Первый день периода для сравнения. Требует `--compare-to`.
`--compare-to`	Нет	Последний день периода для сравнения. Требует `--compare-from`.

When the period has no conversions, meta.recommended_period in the --json output can name a period that has some.

`analytics funnel`

Читает воронку: количество пользователей на каждом шаге — от установки до продлений.

Флаг	Обязательный	Описание
`--group-by`	Нет	Один вариант группировки из каталога.

`analytics retention`

Читает retention: количество оставшихся подписчиков в каждом периоде.

Флаг	Обязательный	Описание
`--group-by`	Нет	Один вариант группировки из каталога.
`--use-trial`	Нет	Считать с момента триала, а не с первого платного периода.

`analytics ltv`

Читает LTV: выручку на одного платящего пользователя после каждого продления или дня.

Флаг	Обязательный	Описание
`--group-by`	Нет	Одна группировка из каталога.
`--revenue-basis`	Нет	`gross` (по умолчанию), `proceeds` или `net`.
`--period-type`	Нет	`renewals` (по умолчанию) — считает по продлениям. `days` — считает по дням с момента установки.
`--renewal-days`	Нет	Дни для подсчёта при `--period-type days`, через запятую в порядке возрастания, например `7,30,90`. Только с `--period-type days`.

`analytics cohort`

Читает когорты установок: выручку, подписчиков, средние значения и прогнозы по каждой когорте с разбивкой по обновлениям или дням. Каждая когорта — одна строка, её дата начала используется как key. Когорты нельзя группировать.

Флаг	Обязательный	Описание
`--granularity`	Нет	Длина одной когорты: `day`, `week`, `month` (по умолчанию), `quarter` или `year`.
`--revenue-basis`	Нет	`gross` (по умолчанию), `proceeds` или `net`.
`--period-type`	Нет	`renewals` (по умолчанию) — подсчёт по продлениям. `days` — подсчёт по дням с момента установки.
`--renewal-days`	Нет	Дни для подсчёта при `--period-type days`, через запятую в порядке возрастания. Только с `--period-type days`.

Что дальше

Как работает аналитика Adapty — откуда берутся данные.
Элементы управления, фильтры и группировка — что означают фильтры и параметры выручки в дашборде.
Запрос атрибуции через CLI — расходы, установки и ROAS по каналам и кампаниям.