---
title: "Запросы к аналитике из CLI"
description: "Читайте аналитику Adapty прямо из терминала: графики выручки и MRR, конверсии, воронка, удержание, LTV и когорты установок — в виде таблицы, JSON или CSV."
---

> **AI agents**: to search Adapty docs faster and with fewer tokens, install the Adapty skills: `npx adapty skills install --yes`

SDK читает [Аналитику Adapty](analytics) прямо из терминала с помощью команд `adapty analytics`. Он возвращает те же данные, что отображаются в разделе Analytics дашборда, для одного приложения: [графики](charts) — доход, MRR и другие, — [конверсии](analytics-conversion), [воронку](analytics-funnels), [удержание](analytics-retention), [LTV](ltv) и [когорты установок](analytics-cohorts).

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

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

## Перед началом работы \{#before-you-start\}

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

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

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

```bash
adapty apps list
```

## Создайте запрос \{#build-a-query\}

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

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

   ```bash
   adapty analytics catalog --app <app-id>
   ```

   Названия графиков и конверсий, такие как `revenue`, `mrr` или `trial-paid`, берутся из этого списка. CLI не хранит собственного списка, поэтому графики, которые Adapty добавит позже, будут работать без обновления CLI.

2. **Найдите значения фильтров**. Пропустите этот шаг, если не используете фильтры. Например, чтобы получить список стран, по которым можно фильтровать:

   ```bash
   adapty analytics values --app <app-id> --dimension country
   ```

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

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

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

### Примеры

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

```bash
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
```

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

```bash
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
```

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

```bash
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-файл:

```bash
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
```

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

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

## Выберите формат вывода \{#choose-the-output\}

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

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

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

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

## Читаем результаты \{#read-the-results\}

- **Даты**: `--date-from` и `--date-to` — это включительные дни в [часовом поясе отчётности](general) приложения. Чтобы читать дни в другом часовом поясе, передайте 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](developer-cli-attribution). Adapty вычисляет их по-разному.

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

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

## Лимиты \{#limits\}

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

## Ошибки \{#errors\}

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

| Код выхода | Причина | Что делать |
|---|---|---|
| 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. При превышении лимита запросов см. раздел [Лимиты](#limits). |

## Справочник команд \{#command-reference\}

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

| Флаг | Обязателен | Описание |
|---|---|---|
| `--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` \{#analytics-chart\}

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

| Флаг | Обязательный | Описание |
|---|---|---|
| `--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` \{#analytics-conversion\}

Считывает одну [конверсию](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`

Читает [воронку](analytics-funnels): количество пользователей на каждом шаге — от установки до продлений.

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

### `analytics retention`

Читает [retention](analytics-retention): количество оставшихся подписчиков в каждом периоде.

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

### `analytics ltv`

Читает [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`

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

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

## Что дальше \{#whats-next\}

- [Как работает аналитика Adapty](how-adapty-analytics-works) — откуда берутся данные.
- [Элементы управления, фильтры и группировка](controls-filters-grouping-compare-proceeds) — что означают фильтры и параметры выручки в дашборде.
- [Запрос атрибуции через CLI](developer-cli-attribution) — расходы, установки и ROAS по каналам и кампаниям.