---
title: "Команды Ads Manager для Adapty Developer CLI"
description: "Справочник по всем командам adapty asa — кампании, группы объявлений, ключевые слова, объявления, автоматизации и метрики."
---

В этой статье перечислены все команды [Ads Manager](adapty-ads-manager) в Adapty CLI с аргументами, флагами и допустимыми значениями. Команды Ads Manager находятся в разделе `adapty asa`.

:::link
Требования, рекомендации по безопасной записи и примеры задач см. в разделе [Управление Ads Manager из CLI](developer-cli-ads-manager).
:::

Для этих команд требуется подключённый аккаунт Apple Ads и активная подписка Ads Manager. Выполните [`adapty asa whoami`](#adapty-asa-whoami), чтобы проверить оба условия. Остальные команды CLI см. в [справочнике команд](developer-cli-reference).

## Глобальные флаги \{#global-flags\}

Эти флаги доступны для всех команд Ads Manager.

| Флаг | Описание |
|---|---|
| `--json` | Вывод в формате JSON вместо форматированного текста |
| `--help` | Показать справку по команде |

Все команды `list` также принимают флаги пагинации:

| Флаг | По умолчанию | Описание |
|---|---|---|
| `--page` | `1` | Номер страницы |
| `--page-size` | `100` | Элементов на странице (макс.: 1000) |

Страницы Ads Manager больше, чем в остальной части CLI. Предпочтительнее одна большая страница, чем цикл из небольших.

Все команды, изменяющие ваш аккаунт, принимают следующие флаги:

| Флаг | Описание |
|---|---|
| `--yes`, `-y` | Применить без запроса подтверждения. Обязателен, когда вывод перенаправляется или используется `--json` |
| `--idempotency-key` | Фиксированный ключ для этой операции записи. Повторный запрос с тем же ключом и телом в течение 24 часов возвращает сохранённый результат вместо повторного применения изменения |

Команды Ads Manager не принимают флаг `--app`. Область действия — компания, которой принадлежит ваш токен. `--app` присутствует в некоторых командах `list` только как фильтр.

## Фильтры списка \{#list-filters\}

Фильтры сужают сам запрос, а не отображаемую страницу. Без фильтров `keywords list` перебирает все ключевые слова в аккаунте, поэтому ограничивайте каждый запрос нужным уровнем.

| Фильтр | Принимается |
|---|---|
| `--campaign-group` | `campaigns`, `ad-groups`, `keywords`, `negative-keywords`, `search-terms`, `ads`, `creatives`, `product-pages` |
| `--app` | `campaigns`, `ad-groups`, `keywords`, `negative-keywords`, `search-terms`, `creatives`, `product-pages` |
| `--campaign` | `ad-groups`, `keywords`, `negative-keywords`, `search-terms`, `ads` |
| `--ad-group` | `keywords`, `negative-keywords`, `search-terms`, `ads` |
| `--status` | `campaigns`, `ad-groups`, `ads` (`ENABLED` или `PAUSED`), `keywords` (`ACTIVE` или `PAUSED`) |
| `--search` | `campaigns`, `ad-groups`, `keywords`, `negative-keywords`, `search-terms`, `ads`. Поиск подстроки в имени без учёта регистра |

`adapty asa apps list`, `orgs list`, `automations list` и `automations runs` не поддерживают фильтры. Они принимают только флаги пагинации.

`--campaign-group`, `--app`, `--campaign` и `--ad-group` принимают UUID, которые выводит соответствующая команда `list`, и каждый из них можно указать несколько раз:

```bash
adapty asa keywords list --ad-group <ad-group-id> --ad-group <other-ad-group-id>
```

Если указать ID, принадлежащий другой компании, страница вернётся пустой — без ошибки.

## Аккаунт \{#account\}

### adapty asa whoami

Показывает компанию, способ предоставления доступа к Ads Manager и статус подключения Apple Ads.

```bash
adapty asa whoami
```

Запустите эту команду первой. Она покажет, выполнены ли два предварительных условия для всех остальных команд.

### adapty asa connect

Подключение Apple Ads аккаунта к Adapty.

```bash
adapty asa connect
```

Команда выводит ссылку для авторизации через Apple и ожидает, пока Apple не сообщит об успешном подключении аккаунта.

| Флаг | По умолчанию | Описание |
|---|---|---|
| `--wait` / `--no-wait` | `--wait` | Ожидать, пока Apple Ads сообщит о подключении. `--no-wait` — вернуть управление немедленно |
| `--timeout` | `300` | Количество секунд ожидания шага в браузере |

### adapty asa orgs list

Выводит список групп кампаний (организаций Apple Ads), доступных вашей компании.

```bash
adapty asa orgs list
```

Каждая строка содержит два идентификатора, которые не взаимозаменяемы:

| Поле | Используется как |
|---|---|
| `internal_id` | UUID, который принимает флаг `--org` в команде [`campaigns create`](#adapty-asa-campaigns-create), а также флаг `--campaign-group` в качестве [фильтра списка](#list-filters) |
| `org_id` | Числовой идентификатор организации Apple. Оба флага его не принимают |

Флаг `--org` существует только в `campaigns create`. Ни одна команда list его не принимает.

Принимает [флаги пагинации](#global-flags).

### adapty asa apps list

Список приложений, продвигаемых в Apple Ads.

```bash
adapty asa apps list
```

Каждая строка содержит два идентификатора, которые не взаимозаменяемы:

| Поле | Используется как |
|---|---|
| `internal_id` | UUID, который принимает `--app` в качестве [фильтра списка](#list-filters) |
| `adam_id` | Числовой App Store ID от Apple, используемый с `--adam-id` в [`campaigns create`](#adapty-asa-campaigns-create) и [`product-pages sync`](#adapty-asa-product-pages-sync) |

Принимает [флаги пагинации](#global-flags).

## Кампании \{#campaigns\}

### adapty asa campaigns list

Список [кампаний](ads-manager-create-campaign). Возвращает только метаданные — для получения показателей производительности используйте [`asa metrics`](#adapty-asa-metrics).

```bash
adapty asa campaigns list --app <app-id> --status PAUSED
```

Принимает [флаги пагинации](#global-flags) и [фильтры списка](#list-filters) `--campaign-group`, `--app`, `--search` и `--status`.

### adapty asa campaigns get

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

```bash
adapty asa campaigns get <campaign-id>
```

| Argument | Description |
|---|---|
| `campaign-id` | Campaign ID (UUID) |

### adapty asa campaigns create

Создание кампании.

```bash
adapty asa campaigns create --org <campaign-group-id> --name "Winter push" --adam-id 123456 --country US --daily-budget 50
```

| Флаг | Обязательный | Описание |
|---|---|---|
| `--org` | Да | ID группы кампаний (UUID). См. [`orgs list`](#adapty-asa-orgs-list) |
| `--name` | Да | Название кампании |
| `--adam-id` | Да | ID приложения в App Store (`adam_id`) |
| `--country` | Да | Код страны или региона. Повторяйте для нескольких: `--country US --country CA` |
| `--daily-budget` | Да | Дневной бюджет в виде числа, например `50` или `12.50` |
| `--budget` | Нет | Общий бюджет |
| `--target-cpa` | Нет | Целевая стоимость привлечения |
| `--currency` | Нет | Код валюты для сумм в этом запросе. По умолчанию: `USD` |
| `--bidding-strategy` | Нет | `MANUAL_CPT` или `MAX_CONVERSIONS`. Apple по умолчанию использует `MANUAL_CPT` |
| `--ad-channel-type` | Нет | `SEARCH` или `DISPLAY`. По умолчанию: `SEARCH` |
| `--billing-event` | Нет | `TAPS` или `IMPRESSIONS`. По умолчанию: `TAPS` |
| `--supply-source` | Нет | Источник инвентаря, повторяемый. По умолчанию: `APPSTORE_SEARCH_RESULTS` |
| `--status` | Нет | Начальный статус: `ENABLED` или `PAUSED` |

### adapty asa campaigns update

Обновите существующую кампанию.

```bash
adapty asa campaigns update <campaign-id> --daily-budget 80 --status PAUSED
```

| Аргумент | Описание |
|---|---|
| `campaign-id` | ID кампании (UUID) |

| Флаг | Описание |
|---|---|
| `--name` | Новое название кампании |
| `--status` | `ENABLED` или `PAUSED` |
| `--country` | Заменяет список стран. Повторите для нескольких |
| `--daily-budget` | Новый дневной бюджет |
| `--budget` | Новый бюджет на весь срок |
| `--target-cpa` | Новая целевая стоимость привлечения |
| `--bidding-strategy` | `MANUAL_CPT` или `MAX_CONVERSIONS` |
| `--currency` | Код валюты для сумм в этом запросе. По умолчанию: `USD` |

Требуется хотя бы один флаг.

## Рекламные группы \{#ad-groups\}

### adapty asa ad-groups list

Список [групп объявлений](ads-manager-create-ad-group). Возвращает только метаданные — для получения показателей производительности используйте [`asa metrics`](#adapty-asa-metrics).

```bash
adapty asa ad-groups list --campaign <campaign-id>
```

Принимает [флаги пагинации](#global-flags) и [фильтры списка](#list-filters) `--campaign-group`, `--app`, `--campaign`, `--search` и `--status`.

### adapty asa ad-groups get

Получить подробную информацию о конкретной группе объявлений.

```bash
adapty asa ad-groups get <ad-group-id>
```

| Аргумент | Описание |
|---|---|
| `ad-group-id` | ID группы объявлений (UUID) |

### adapty asa ad-groups create

Создание группы объявлений в кампании.

```bash
adapty asa ad-groups create --campaign <campaign-id> --name "Brand terms" --default-bid 1.20
```

| Флаг | Обязательный | Описание |
|---|---|---|
| `--campaign` | Да | ID кампании (UUID) |
| `--name` | Да | Название группы объявлений |
| `--default-bid` | Да | Ставка по умолчанию в виде числа, например `1.20` |
| `--cpa-goal` | Нет | Целевая стоимость привлечения |
| `--pricing-model` | Нет | `CPC` или `CPM`. Apple требует указать для каждой группы объявлений. По умолчанию: `CPC` |
| `--start-time` | Нет | Начало расписания (`YYYY-MM-DD`). По умолчанию — сегодня |
| `--end-time` | Нет | Конец расписания (`YYYY-MM-DD`) |
| `--automated-keywords` / `--no-automated-keywords` | Нет | Разрешить Apple автоматически добавлять ключевые слова |
| `--currency` | Нет | Код валюты для сумм в этом запросе. По умолчанию: `USD` |
| `--status` | Нет | Начальный статус: `ENABLED` или `PAUSED` |

### adapty asa ad-groups update

Обновить существующую группу объявлений.

```bash
adapty asa ad-groups update <ad-group-id> --default-bid 1.50 --status PAUSED
```

| Аргумент | Описание |
|---|---|
| `ad-group-id` | ID группы объявлений (UUID) |

| Флаг | Описание |
|---|---|
| `--name` | Новое название группы объявлений |
| `--status` | `ENABLED` или `PAUSED` |
| `--default-bid` | Новая ставка по умолчанию |
| `--cpa-goal` | Новая целевая стоимость привлечения |
| `--start-time` | Начало расписания (`YYYY-MM-DD`) |
| `--end-time` | Конец расписания (`YYYY-MM-DD`) |
| `--automated-keywords` / `--no-automated-keywords` | Разрешить Apple автоматически добавлять ключевые слова |
| `--currency` | Код валюты для сумм в этом запросе. По умолчанию: `USD` |

Необходим хотя бы один флаг. Родительская кампания определяется на сервере и никогда не передаётся напрямую.

## Ключевые слова \{#keywords\}

Команды для ключевых слов применяются пакетами не более 100 элементов за один вызов. Эквивалент в дашборде см. в разделе [Управление ключевыми словами](ads-manager-manage-keywords).

### adapty asa keywords list

Выводит список таргетинговых ключевых слов. Возвращает только метаданные — для просмотра показателей производительности используйте [`asa metrics`](#adapty-asa-metrics).

```bash
adapty asa keywords list --ad-group <ad-group-id> --status ACTIVE
```

Принимает [флаги пагинации](#global-flags) и [фильтры списка](#list-filters) `--campaign-group`, `--app`, `--campaign`, `--ad-group`, `--search` и `--status`. Фильтруйте по `--ad-group` — без фильтра это самый широкий запрос по данной теме.

### adapty asa keywords add

Добавьте ключевые слова таргетинга в группу объявлений.

```bash
adapty asa keywords add --ad-group <ad-group-id> --text "running shoes" --text "trail shoes" --bid 1.20
```

Считайте ключевые слова из файла — по одному на строку:

```bash
adapty asa keywords add --ad-group <ad-group-id> --from-file keywords.txt
```

| Флаг | Обязательный | Описание |
|---|---|---|
| `--ad-group` | Да | ID группы объявлений (UUID). Из него определяется кампания |
| `--text` | Да, если не используется `--from-file` | Текст ключевого слова. Повторите для нескольких |
| `--from-file` | Нет | Файл с одним ключевым словом на строку. Объединяется с любыми значениями `--text` |
| `--bid` | Нет | Ставка за ключевое слово в виде числового значения |
| `--match-type` | Нет | `BROAD` или `EXACT`. По умолчанию: `BROAD` |
| `--currency` | Нет | Код валюты для сумм в этом запросе. По умолчанию: `USD` |
| `--status` | Нет | `ACTIVE` или `PAUSED`. По умолчанию: `ACTIVE` |

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

### adapty asa keywords update

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

```bash
adapty asa keywords update <keyword-id> <keyword-id> --bid 2.00 --status PAUSED
```

| Аргумент | Описание |
|---|---|
| `keyword-id` | ID ключевого слова (UUID). Чтобы передать несколько, укажите их как дополнительные аргументы |

| Флаг | Описание |
|---|---|
| `--bid` | Новая ставка |
| `--status` | `ACTIVE` или `PAUSED` |
| `--match-type` | `BROAD` или `EXACT` |
| `--text` | Новый текст ключевого слова. Имеет смысл только при обновлении одного ключевого слова |
| `--currency` | Код валюты для сумм в этом вызове. По умолчанию: `USD` |

Одно изменение применяется к каждому переданному ID.

## Негативные ключевые слова \{#negative-keywords\}

### adapty asa negative-keywords list

Выводит список минус-слов. Строки с пустым `ad_group_id` относятся к уровню кампании.

```bash
adapty asa negative-keywords list --campaign <campaign-id>
```

| Флаг | Описание |
|---|---|
| `--campaign-level-only` | Оставить только строки уровня кампании |

Принимает [флаги пагинации](#global-flags) и [фильтры списка](#list-filters) `--campaign-group`, `--app`, `--campaign`, `--ad-group` и `--search`.

### adapty asa negative-keywords add

Добавление минус-слов в группу объявлений или кампанию.

```bash
adapty asa negative-keywords add --ad-group <ad-group-id> --text free
```

Применить ко всем группам объявлений кампании:

```bash
adapty asa negative-keywords add --campaign <campaign-id> --all-ad-groups --text free
```

| Флаг | Обязательный | Описание |
|---|---|---|
| `--ad-group` | Одно из `--ad-group` или `--campaign` | ID группы объявлений (UUID). Кампания определяется из него |
| `--campaign` | Одно из `--ad-group` или `--campaign` | ID кампании (UUID) |
| `--text` | Да | Текст ключевого слова. Повторите для нескольких |
| `--all-ad-groups` | Нет | Применить ко всем группам объявлений кампании вместо самой кампании. Требует `--campaign` |
| `--match-type` | Нет | `BROAD` или `EXACT`. По умолчанию: `EXACT` |
| `--status` | Нет | `ACTIVE` или `PAUSED`. По умолчанию: `ACTIVE` |

`--ad-group` и `--campaign` являются взаимоисключающими. Передайте ровно один из них.

## Условия поиска \{#search-terms\}

### adapty asa search-terms list

Список поисковых запросов, которые запустили ваши объявления. Используйте его для поиска новых ключевых слов и минус-слов.

```bash
adapty asa search-terms list --ad-group <ad-group-id> --date-from 2026-07-01 --date-to 2026-07-31
```

| Флаг | По умолчанию | Описание |
|---|---|---|
| `--date-from` | Сегодня | Начало отчётного периода (`YYYY-MM-DD`) |
| `--date-to` | Сегодня | Конец отчётного периода (`YYYY-MM-DD`) |

Принимает [флаги пагинации](#global-flags) и [фильтры списка](#list-filters) `--campaign-group`, `--app`, `--campaign`, `--ad-group` и `--search`.

Эта команда использует общий пул аналитики с [`asa metrics`](#metrics). См. [Ошибки](#errors).

## Реклама \{#ads\}

### adapty asa ads list

Выводит список [объявлений](ads-manager-manage-ads). Поле `serving_state_reasons` объясняет, почему объявление не показывается.

```bash
adapty asa ads list --ad-group <ad-group-id>
```

Принимает [флаги пагинации](#global-flags) и [фильтры списка](#list-filters) `--campaign-group`, `--campaign`, `--ad-group`, `--search` и `--status`. У этого списка нет фильтра `--app`, поскольку объявления принадлежат группам объявлений.

### adapty asa ads get

Получить детали конкретного объявления.

```bash
adapty asa ads get <ad-id>
```

| Аргумент | Описание |
|---|---|
| `ad-id` | ID объявления (UUID) |

### adapty asa ads create

Создать объявление в группе объявлений.

```bash
adapty asa ads create --ad-group <ad-group-id> --creative-id 4321 --name "Summer ad"
```

| Флаг | Обязателен | Описание |
|---|---|---|
| `--ad-group` | Да | ID группы объявлений (UUID). Кампания определяется из него |
| `--creative-id` | Да | Apple creative ID. См. [`creatives list`](#adapty-asa-creatives-list) |
| `--name` | Да | Название объявления |
| `--status` | Нет | Начальный статус: `ENABLED` или `PAUSED` |

### adapty asa ads update

Обновление существующего объявления.

```bash
adapty asa ads update <ad-id> --status PAUSED
```

| Аргумент | Описание |
|---|---|
| `ad-id` | ID объявления (UUID) |

| Флаг | Описание |
|---|---|
| `--name` | Новое название объявления |
| `--status` | `ENABLED` или `PAUSED` |

Необходимо указать хотя бы один флаг. Креатив и родительская группа объявлений фиксируются при создании.

## Креативы \{#creatives\}

### adapty asa creatives list

Список креативов, доступных для новых объявлений.

```bash
adapty asa creatives list --app <app-id>
```

`creative_id`, возвращаемый здесь, является значением `--creative-id` для [`ads create`](#adapty-asa-ads-create).

Принимает [флаги пагинации](#global-flags) и [фильтры списка](#list-filters) `--campaign-group` и `--app`.

## Страницы продуктов \{#product-pages\}

### adapty asa product-pages list

Выводит список доступных пользовательских страниц продукта для ваших приложений.

```bash
adapty asa product-pages list --app <app-id>
```

Принимает [флаги пагинации](#global-flags), а также фильтры `--campaign-group` и `--app` из раздела [фильтры списка](#list-filters).

### adapty asa product-pages sync

Обновить кастомные страницы продукта из App Store Connect.

```bash
adapty asa product-pages sync --adam-id 123456
```

| Флаг | Описание |
|---|---|
| `--adam-id` | Ограничить обновление одним приложением. Если не указан, охватывает все приложения |

Обновление ставится в очередь, а не выполняется сразу — команда подтверждает это сообщением `Sync queued.`. Если такое же обновление уже выполняется, вместо этого выводится `Already running; nothing new was queued.`

## Автоматизации \{#automations\}

CLI хранит JSON с правилами, которые вы ему передаёте, — он не строит правила самостоятельно. Подробнее о типах правил см. в разделе [Автоматизации](ads-manager-automations), а о том, как создать файл с правилами, — в разделе [Запуск правил автоматизации](developer-cli-ads-manager#run-automation-rules).

### adapty asa automations list

Список [правил автоматизации](ads-manager-automations). Поле `status` принимает значение `1` для активных и `0` для остановленных.

```bash
adapty asa automations list
```

Принимает [флаги пагинации](#global-flags).

### adapty asa automations get

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

```bash
adapty asa automations get <automation-id>
```

| Argument | Description |
|---|---|
| `automation-id` | Automation rule ID (UUID) |

### adapty asa automations create

Создаёт правило автоматизации из JSON-файла.

```bash
adapty asa automations create --file rule.json
```

| Флаг | Описание |
|---|---|
| `--file` | JSON-файл с телом правила или `-` для чтения из стандартного ввода |
| `--run-now` | Ставит первый запуск в очередь сразу после сохранения правила |

`--file` обязателен.

### adapty asa automations update

Изменить правило автоматизации: остановить его, переименовать или заменить части правила.

```bash
adapty asa automations update <automation-id> --stop
```

| Аргумент | Описание |
|---|---|
| `automation-id` | ID правила автоматизации (UUID) |

| Флаг | Описание |
|---|---|
| `--start` | Активировать правило |
| `--stop` | Остановить правило и сбросить время следующего запуска |
| `--name` | Новое имя правила |
| `--file` | JSON-файл с изменяемыми частями или `-` для чтения из стандартного ввода |

`--start` и `--stop` взаимно исключают друг друга. Файл, переданный здесь, не должен содержать `internal_id`.

### adapty asa automations run

Запустить правило автоматизации один раз, вне расписания.

```bash
adapty asa automations run <automation-id> --dry-run
```

| Аргумент | Описание |
|---|---|
| `automation-id` | ID правила автоматизации (UUID) |

| Флаг | Описание |
|---|---|
| `--dry-run` | Проверить правило и записать результат в лог без изменений в Apple Ads |

Запуск ставится в очередь, и команда выводит ID запуска. Просмотреть результат можно с помощью [`automations runs`](#adapty-asa-automations-runs).

### adapty asa automations runs

Список прошедших запусков правила автоматизации, включая тестовые (dry run).

```bash
adapty asa automations runs <automation-id>
```

| Аргумент | Описание |
|---|---|
| `automation-id` | ID правила автоматизации (UUID) |

Принимает [флаги пагинации](#global-flags).

## Метрики \{#metrics\}

### adapty asa metrics

Запрашивает метрики для любого уровня аккаунта за указанный диапазон дат.

```bash
adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31
```

| Флаг | Обязательный | Описание |
|---|---|---|
| `--entity` | Да | По чему строить отчёт: `campaign`, `ad-group`, `keyword` или `ad` |
| `--date-from` | Да | Начало периода (`YYYY-MM-DD`) |
| `--date-to` | Да | Конец периода (`YYYY-MM-DD`) |
| `--metric` | Нет | Название метрики, можно указывать несколько раз. Пропустите, чтобы получить все метрики |
| `--group-by` | Нет | Разбивка строк по `country`, `day`, `week`, `month`, `quarter` или `year`. Можно указывать несколько раз |
| `--by-days` | Нет | Окно продлений в днях для когортных метрик, можно указывать несколько раз. Максимум 16 за один вызов. Пропустите, чтобы использовать значения по умолчанию из дашборда |
| `--order-by` | Нет | Метрика или поле для сортировки |
| `--order-by-day` | Нет | Ранжировать по когортной метрике в этом окне продлений. Должно быть одним из значений `--by-days` |
| `--order` | Нет | `asc` или `desc`. По умолчанию: `desc` |

Принимает [флаги пагинации](#global-flags). Эта команда не принимает [фильтры списков](#list-filters) — сузьте отчёт по уровню сущности и периоду, а затем сопоставьте строки с ID из команды `list` с нужной областью.

Каждая строка — одна сущность, агрегированная на сервере и отсортированная по `--order-by`. Вопрос «топ-N» решается одним запросом — задайте `--order-by` и `--page-size N` вместо того, чтобы листать результаты и складывать их вручную:

```bash
adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --order-by spend --page-size 5
```

`--metric` принимает названия метрик, которые отслеживает Ads Manager, в номенклатуре дашборда — например `spend`, `taps` или `gross_roas`. Полный список и описание расчёта каждой метрики см. в разделе [Метрики](adapty-ads-manager-metrics). Несуществующее название приведёт к ошибке с перечнем допустимых значений.

Длина периода отчёта ограничена наиболее крупным значением `--group-by`. Чтобы охватить более длинный период, укрупните группировку вместо того, чтобы разбивать запрос на несколько вызовов:

| Самая крупная единица `--group-by` | Максимальный период |
|---|---|
| `day` или без группировки по периоду | 90 дней |
| `week` | 180 дней |
| `month` и крупнее | 365 дней |

Метрики `ltv` не существует. Lifetime value — это когортная метрика, считываемая в окне продления, поэтому для получения значений на 7-й или 90-й день используется `--by-days`:

```bash
adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric roas --by-days 7 --by-days 90
```

`--order-by-day` сортирует строки по одному из этих окон — так можно получить топ кампаний по ROAS на 90-й день за один запрос.

### adapty asa metrics overview

Query totals for a period, bucketed by a unit of time.

```bash
adapty asa metrics overview --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --period-unit week
```

| Флаг | Обязательный | Описание |
|---|---|---|
| `--entity` | Да | По какому объекту строить отчёт: `campaign`, `ad-group`, `keyword` или `ad` |
| `--date-from` | Да | Начало периода (`YYYY-MM-DD`) |
| `--date-to` | Да | Конец периода (`YYYY-MM-DD`) |
| `--period-unit` | Нет | Размер бакета: `day`, `week`, `month`, `quarter` или `year`. По умолчанию: `day` |
| `--metric` | Нет | Название метрики, можно указывать несколько раз. Не указывайте, чтобы получить все метрики |
| `--by-days` | Нет | Окно продлений в днях для метрик когорт, можно указывать несколько раз. Максимум 16 за один вызов |

Эта команда возвращает итоги по всей выбранной сущности и разбивку по периодам, то есть отвечает на вопрос «сколько я потратил или заработал в целом» за один вызов. Флаги сортировки и пагинация отсутствуют.

Для этой команды `--metric` принимает только корневые когортные метрики — `revenue`, `roas` и `arpu` — без вариантов `gross_`, `proceeds_` и `net_`.

Длина отчётного периода ограничена параметром `--period-unit`:

| `--period-unit` | Максимальный период |
|---|---|
| `day` | 90 дней |
| `week` | 180 дней |
| `month` и крупнее | 365 дней |

## Конкуренты \{#competitors\}

### adapty asa competitors summary

Показывает сводку по ключевым словам Apple Ads, на которые делает ставки набор приложений из App Store. Возвращает те же данные о конкурентах, что и [Market Intelligence](ads-manager-market-intelligence) в дашборде.

```bash
adapty asa competitors summary --app-ids 1668337467,6503873027
```

| Флаг | Обязательный | Описание |
|---|---|---|
| `--app-ids` | Да | ID приложений в Apple App Store (`adam_id`), через запятую. От 1 до 5 значений |

Отчётный период и набор стран фиксированы на сервере — последний полный месяц, все страны. У команды нет флагов для периода, страны или пагинации.

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

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

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

| Статус | Код | Значение |
|---|---|---|
| `402` | `ads_manager_subscription_required` | У компании нет активной подписки Ads Manager |
| `404` | — | Сущность не существует или принадлежит другой компании |
| `409` | `cli_idempotency_in_progress` | Запрос с тем же ключом идемпотентности ещё выполняется |
| `422` | `cli_idempotency_key_reuse` | Тот же ключ идемпотентности был использован с другим телом запроса |
| `429` | `cli_analytics_busy` | Пул аналитики занят. Время ожидания указано в заголовке `Retry-After` |
| `429` | `cli_cooldown_active` | Слишком много отклонённых запросов перевели токен в режим ожидания |

Метрики и список поисковых запросов используют общий аналитический бюджет на уровне компании: 5 запросов в минуту, и не более 2 за любые 10 секунд. Если за 5 минут накапливается 20 отклонённых запросов, включается нарастающий период ожидания: сначала 5 минут, затем 30 минут, затем 3 часа. Повторные запросы во время паузы её не продлевают, однако правильное решение — исправить проблемный запрос, а не отправлять его снова.

CLI самостоятельно обрабатывает короткие ожидания. Если в ответ на `429` (не связанный с периодом ожидания) заголовок `Retry-After` указывает не более 60 секунд, команда ждёт указанное время и повторяет запрос один раз, выводя информацию об ожидании в стандартный поток ошибок.