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

Для выполнения этих команд необходимы подключённый аккаунт Apple Ads и активная подписка Ads Manager. Выполните adapty asa whoami, чтобы проверить оба условия. Остальные команды CLI описаны в справочнике команд.

Глобальные флаги

Эти флаги доступны для всех команд 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 только как фильтр. Исключение составляют команды segments: там --app — это приложение Adapty, которому принадлежит сегмент.

Фильтры списка

Фильтры сужают сам запрос, а не отображаемую страницу. Без фильтров 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, и каждый из них можно указать несколько раз:

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

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

Аккаунт

adapty asa whoami

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

adapty asa whoami

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

adapty asa connect

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

adapty asa connect

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

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

adapty asa orgs list

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

adapty asa orgs list

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

Поле	Используется как
internal_id	UUID, который принимает --org в campaigns create, а также --campaign-group в качестве фильтра списка
org_id	Числовой идентификатор организации Apple, принимаемый --org-id в campaigns bulk-create. --org и --campaign-group его не принимают

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

Каждая строка также содержит поле payment_model. Если его значение равно LOC, организация выставляет счёт по кредитной линии, и каждая кампания в ней требует флагов --invoice-*.

Принимает флаги пагинации.

adapty asa apps list

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

adapty asa apps list

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

Поле	Используется как
internal_id	UUID, который принимает --app в качестве фильтра списка
adam_id	Числовой App Store ID от Apple, используемый с --adam-id в campaigns create и product-pages sync

Принимает флаги пагинации.

Кампании

adapty asa campaigns list

Список кампаний. Возвращает только метаданные — для получения показателей производительности используйте asa metrics.

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

Принимает флаги пагинации и фильтры списка --campaign-group, --app, --search и --status.

adapty asa campaigns get

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

adapty asa campaigns get <campaign-id>

Argument	Description
campaign-id	Campaign ID (UUID)

adapty asa campaigns create

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

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

Флаг	Обязательный	Описание
--org	Да	ID группы кампаний (UUID). См. orgs list
--name	Да	Название кампании
--adam-id	Да	ID приложения в App Store (adam_id)
--country	Да	Код страны или региона. Для нескольких: --country US --country CA
--daily-budget	Да	Дневной бюджет в виде числа, например 50 или 12.50
--budget	Нет	Общий бюджет
--target-cpa	Нет	Целевая стоимость привлечения. Должна быть ниже --daily-budget
--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
--invoice-advertiser	Кредитная линия	Параметры выставления счёта: имя рекламодателя
--invoice-order-number	Кредитная линия	Параметры выставления счёта: номер заказа
--invoice-contact-name	Кредитная линия	Параметры выставления счёта: имя контактного лица покупателя
--invoice-contact-email	Кредитная линия	Параметры выставления счёта: email контактного лица покупателя
--invoice-billing-email	Кредитная линия	Параметры выставления счёта: email для выставления счёта

Организация с payment_model равным LOC выставляет счета по кредитной линии, и Apple требует указания параметров выставления счёта для каждой из её кампаний. Передавайте все пять флагов --invoice-* в одном вызове — неполный набор отклоняется до отправки запроса. См. Настройка параметров выставления счёта для кредитной линии.

Ответ содержит serving_status и serving_state_reasons. Кампания может быть создана, но не запущена: кампания с типом MAX_CONVERSIONS ждёт автоматической группы объявлений, а кампания с кредитной линией ждёт настройки параметров выставления счетов. В обоих случаях команда выводит причину и команду, которая её устраняет.

adapty asa campaigns update

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

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
--invoice-advertiser	Параметры выставления счёта: название рекламодателя
--invoice-order-number	Параметры выставления счёта: номер заказа
--invoice-contact-name	Параметры выставления счёта: контактное имя покупателя
--invoice-contact-email	Параметры выставления счёта: контактный email покупателя
--invoice-billing-email	Параметры выставления счёта: email для выставления счёта

По меньшей мере один флаг обязателен.

Пять флагов --invoice-* работают как единое целое и полностью заменяют сохранённые параметры выставления счёта, поэтому передавайте все пять даже при изменении одного из них. Неполный набор отклоняется ещё до отправки запроса.

adapty asa campaigns bulk-create

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

adapty asa campaigns bulk-create --file structure.json

Конвертируйте нативный шаблон Apple Ads bulk вместо того, чтобы писать JSON вручную:

adapty asa campaigns bulk-create --from-file Campaign_And_Adgroup_Template.xlsx --org-id 1234567

Флаг	По умолчанию	Описание
--file	—	JSON-файл со структурой кампании или - для чтения из стандартного ввода
--from-file	—	Bulk-шаблон Apple Ads для конвертации на сервере: Campaign_And_Adgroup_Template.xlsx или ключевые слова .csv
--org-id	—	Числовой идентификатор организации Apple (org_id). См. orgs list. Обязателен при использовании --from-file
--preview	—	С --from-file: выводит сконвертированную структуру и завершает работу. Ничего не создаётся
--wait / --no-wait	--wait	Отслеживает операцию до её завершения. --no-wait выводит ID операции и возвращает управление
--poll-interval	5	Интервал между проверками прогресса в секундах
--timeout	900	Максимальное время ожидания завершения операции в секундах

Exactly one of --file and --from-file is required.

The structure names the campaign group at the top level and nests everything else:

{
  "campaign_group_id": 555777,
  "campaigns": [
    {
      "payload": {
        "name": "US Search",
        "adam_id": 123456,
        "countries_or_regions": ["US"],
        "daily_budget_amount": { "amount": "100", "currency": "USD" },
        "status": "ENABLED",
        "ad_channel_type": "SEARCH",
        "billing_event": "TAPS",
        "supply_sources": ["APPSTORE_SEARCH_RESULTS"]
      },
      "ad_groups": [
        {
          "payload": { "name": "Brand", "start_time": "2026-08-01T00:00:00Z", "status": "ENABLED" },
          "keywords": [{ "text": "meditation app", "match_type": "BROAD" }]
        }
      ]
    }
  ]
}

campaign_group_id принимает числовой идентификатор организации Apple; используйте campaign_group_internal_id, чтобы передать UUID. Узел с payload создаётся как новый объект. Узел, указывающий на существующий объект по его id, является якорем — используйте его, чтобы добавить группы объявлений в существующую кампанию, а поле update_payload позволяет изменить сам объект в той же операции. Внутри кампании вложены ad_groups, а внутри каждой группы объявлений — keywords, negative_keywords и ads. Кроме того, кампания принимает negative_keywords напрямую — для минус-слов на уровне кампании.

Вся структура проверяется перед созданием, а при отклонении выводится список всех некорректных узлов. При использовании --from-file ошибки конвертации сообщаются с указанием листа, строки и столбца; предупреждения конвертации не останавливают отправку, а ошибки конвертации прерывают её. Перед отправкой команда показывает количество кампаний, групп объявлений, ключевых слов, минус-слов и объявлений в структуре и запрашивает подтверждение.

Затем команда отслеживает операцию и выводит прогресс вплоть до одного из трёх финальных статусов:

Статус	Значение
success	Все объекты созданы
partial	Некоторые объекты не были созданы. Каждая ошибка выводится с сообщением от Apple
failed	Операция завершилась с ошибкой, команда возвращает ненулевой код выхода

Если операция не завершилась за --timeout секунд, команда возвращает управление и выводит вызов bulk-status для последующего запуска.

adapty asa campaigns bulk-status

Показывает ход выполнения одной массовой операции: статус, количество объектов и журнал по каждому объекту.

adapty asa campaigns bulk-status <operation-id>

Аргумент	Описание
operation-id	ID операции (UUID), выведенный командой campaigns bulk-create

Поле status принимает значения pending, running, success, partial или failed. Блок counts показывает, сколько объектов применено, завершилось с ошибкой и ожидает выполнения от общего числа.

Принимает флаги пагинации.

Рекламные группы

adapty asa ad-groups list

Список групп объявлений. Возвращает только метаданные — для получения показателей производительности используйте asa metrics.

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

Принимает флаги пагинации и фильтры списка --campaign-group, --app, --campaign, --search и --status.

adapty asa ad-groups get

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

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

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

adapty asa ad-groups create

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

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

Флаг	Обязателен	Описание
--campaign	Да	ID кампании (UUID)
--name	Да	Название группы объявлений
--default-bid	Если не указан --automated	Ставка по умолчанию в виде числа, например 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 автоматически добавлять ключевые слова
--automated	Нет	Создать автоматизированную группу объявлений, необходимую для кампании MAX_CONVERSIONS
--currency	Нет	Код валюты для сумм в этом запросе. По умолчанию: USD
--status	Нет	Начальный статус: ENABLED или PAUSED

--automated включает автоматический подбор ключевых слов для группы объявлений, поэтому его нельзя комбинировать с --automated-keywords. Apple самостоятельно управляет расписанием автоматизированной группы объявлений и держит её включённой, поэтому --start-time и --status PAUSED не поддерживаются — чтобы поставить на паузу, остановите кампанию. См. Создание кампании Max Conversions.

adapty asa ad-groups update

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

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

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

Ключевые слова

Команды для ключевых слов применяются пакетами не более 100 элементов за один вызов. Эквивалент в дашборде см. в разделе Управление ключевыми словами.

adapty asa keywords list

Выводит список таргетинговых ключевых слов. Возвращает только метаданные — для просмотра показателей производительности используйте asa metrics.

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

Принимает флаги пагинации и фильтры списка --campaign-group, --app, --campaign, --ad-group, --search и --status. Фильтруйте по --ad-group — без фильтра это самый широкий запрос по данной теме.

adapty asa keywords recommend

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

adapty asa keywords recommend --adam-id <adam-id> --type generic --country US

Флаг	Обязательный	Описание
--adam-id	Да	Apple App Store ID (adam_id) вашего приложения, из asa apps list
--type	Да	brand, generic или competitor
--country	Нет	Двухбуквенный код страны ISO. Повторите для нескольких стран. По умолчанию: все страны в пуле

Флаг --type выбирает пул:

Тип	Ключевые слова
brand	Брендовые запросы вашего приложения, их варианты написания и органические запросы, содержащие бренд. В результатах также перечислены сами брендовые запросы
generic	Небрендовые запросы, по которым ранжируется ваше приложение и его главные органические конкуренты, — с удалёнными брендовыми запросами. relevance_tier: top_organic отмечает запросы, по которым ваше приложение уже занимает позиции в органическом топ-10
competitor	Брендовые запросы каждого конкурента, выбранного для приложения в AI Growth Advisor, по одному пулу на конкурента. Остаётся пустым до выбора конкурентов

Каждое ключевое слово содержит страну, популярность, оценку и медианный органический ранг. Ставки и типы соответствия не заданы — выберите их самостоятельно, затем добавьте ключевые слова с помощью asa keywords add.

Проверьте status пула перед использованием его ключевых слов:

Статус	Значение
ready	Пул сформирован
building	Пул ещё формируется. Повторите попытку примерно через минуту
empty	Пул сформирован, но не содержит ключевых слов
failed	Формирование завершилось ошибкой. Повторите попытку позже

Первый вызов brand или generic для приложения формирует пул во время запроса и может занять несколько десятков секунд. Команда имеет лимит 10 вызовов в минуту на компанию, и одновременно выполняется только одна сборка brand или generic на компанию. Второй вызов в это время вернёт 429 cli_analytics_busy с заголовком Retry-After: 5.

adapty asa keywords add

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

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

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

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

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

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.

Негативные ключевые слова

adapty asa negative-keywords list

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

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

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

Принимает флаги пагинации и фильтры списка --campaign-group, --app, --campaign, --ad-group и --search.

adapty asa negative-keywords add

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

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

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

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 являются взаимоисключающими. Передайте ровно один из них.

Условия поиска

adapty asa search-terms list

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

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)

Принимает флаги пагинации и фильтры списка --campaign-group, --app, --campaign, --ad-group и --search.

Помимо метрик эффективности, каждая строка поискового запроса содержит инсайты Apple по этому запросу:

Поле	Значение
impression_share_all, impression_share_first	Доля показов на любой позиции объявления или на первой позиции
impression_midpoint_all, impression_midpoint_first	Доля показов в виде единого процентного показателя
rank_all, rank_first	Позиция вашего приложения относительно других приложений по запросу — на любой позиции объявления или на первой
search_popularity	Популярность поиска от 1 до 5

Каждое поле равно null, если у Apple нет данных по этому показателю. Описание значений смотрите в разделе Insights.

Эта команда использует общий пул аналитики с asa metrics. См. раздел Ошибки.

Реклама

adapty asa ads list

Выводит список объявлений. Поле serving_state_reasons объясняет, почему объявление не показывается.

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

Принимает флаги пагинации и фильтры списка --campaign-group, --campaign, --ad-group, --search и --status. У этого списка нет фильтра --app, поскольку объявления принадлежат группам объявлений.

adapty asa ads get

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

adapty asa ads get <ad-id>

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

adapty asa ads create

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

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
--name	Да	Название объявления
--status	Нет	Начальный статус: ENABLED или PAUSED

adapty asa ads update

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

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

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

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

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

Креативы

adapty asa creatives list

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

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

creative_id, возвращаемый здесь, является значением --creative-id для ads create.

Принимает флаги пагинации и фильтры списка --campaign-group и --app.

Страницы продуктов

adapty asa product-pages list

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

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

Принимает флаги пагинации, а также фильтры --campaign-group и --app из раздела фильтры списка.

adapty asa product-pages sync

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

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

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

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

Сегменты

Эти команды создают сегменты Adapty из кампаний, групп объявлений или ключевых слов Apple Ads — так же, как Create segment from… в Ads Manager. Используйте сегменты как аудитории в плейсментах и A/B-тестах, чтобы показывать пользователям из конкретной кампании другой пейвол.

Каждый сегмент содержит один фильтр атрибуции по Apple ID выбранных сущностей. CLI самостоятельно ищет эти ID, поэтому вы передаёте UUID, которые выводят команды list.

В отличие от других команд adapty asa, эти принимают --app: идентификатор приложения Adapty, которому принадлежит сегмент, из adapty apps list. Они не принимают --idempotency-key. Для сегментов с другими фильтрами, такими как страна или дата установки, используйте adapty segments create.

adapty asa segments create

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

adapty asa segments create --app <app-id> --campaign <campaign-id>
adapty asa segments create --app <app-id> --ad-group <ad-group-id> --keyword <keyword-id> --keyword <other-keyword-id>

Флаг	Обязательный	Описание
--app	Да	ID приложения Adapty (UUID)
--campaign	Один тип сущности	ID кампании (UUID). Можно указывать несколько раз
--ad-group	Один тип сущности	ID группы объявлений (UUID). Можно указывать несколько раз. При использовании с --keyword укажите ровно одну: группу объявлений, содержащую ключевые слова
--keyword	Один тип сущности	ID ключевого слова (UUID). Можно указывать несколько раз. Требует одного --ad-group
--title	Нет	Название сегмента. По умолчанию используется формат Ads Manager, например [ASA] Campaign: <name>
--description	Нет	Описание сегмента. По умолчанию используется формат Ads Manager

Каждый сегмент строится из одного типа сущностей. Одновременная передача --campaign и --ad-group, или --campaign вместе с --keyword, приводит к ошибке с кодом выхода 2 до отправки любого запроса. Несколько сущностей одного типа создают один сегмент, охватывающий пользователей из любой из них.

Оставьте заголовок по умолчанию, если не требуется другой. Ads Manager распознаёт свои сегменты по префиксу [ASA], а asa segments list показывает только сегменты с этим префиксом.

Ответ содержит весь сегмент, включая id и filters. profile_count начинается с 0, и Adapty пересчитывает его после создания сегмента.

adapty asa segments update

Замените кампании, группы объявлений или ключевые слова существующего сегмента.

adapty asa segments update <segment-id> --app <app-id> --campaign <campaign-id> --campaign <other-campaign-id>

Аргумент	Описание
segment-id	ID сегмента (UUID), из asa segments list или adapty segments list

Принимает те же флаги, что и asa segments create. Фильтр сегмента заменяется теми сущностями, которые вы передаёте. Название и описание остаются прежними, если вы не передаёте --title или --description.

adapty asa segments list

Список сегментов, созданных на основе сущностей Apple Ads, — тех, чьё название начинается с [ASA].

adapty asa segments list --app <app-id> --campaign <campaign-id>

Флаг	Обязателен	Описание
--app	Да	ID приложения Adapty (UUID)
--campaign	Нет	Оставить только сегменты, построенные на основе этой кампании (UUID)
--ad-group	Нет	Оставить только сегменты, построенные на основе этой группы объявлений (UUID)

Передайте --campaign или --ad-group, но не оба сразу. Чтобы не создавать второй сегмент для той же кампании, выполните эту команду перед asa segments create: пустой результат означает, что у кампании ещё нет сегмента.

Команда читает первые 100 сегментов приложения.

Автоматизации

CLI сохраняет JSON-правило, которое вы передаёте, с одним исключением: настройки действия Add as keyword задаются через флаги. Смотрите Автоматизации для описания каждого типа правил и Запуск правил автоматизации — для создания файла правила.

Флаги действия «добавить как ключевое слово»

Команды automations create и automations update имеют общий набор флагов, задающих actions[0].params для действия add-as-keyword-to — Add as keyword в правиле поисковых запросов, Add as keyword to… в правиле для ключевых слов. Передача любого из этих флагов заменяет весь объект params, поэтому вводить JSON вручную для этого действия не нужно.

Флаг	JSON-поле	Описание
--target-ad-group	targets.internal_ids	Группа объявлений, получающая ключевое слово (UUID), может повторяться. Правило без целевой группы объявлений не делает ничего
--match-type	match_type	BROAD или EXACT
--cpt-bid-type	cpt_bid.type	Источник ставки для нового ключевого слова: ad_group_default_bid, set_to, search_term_current_cpt или keyword_current_bid
--cpt-bid	cpt_bid.value	При set_to — сама ставка. При search_term_current_cpt или keyword_current_bid — процентная наценка к копируемой ставке. Не принимается при ad_group_default_bid
--negate	negate	Также добавляет поисковый запрос как минус-слово — в своей ad-group или своей campaign. --no-negate не оставляет минус-слов. Только для правил поисковых запросов
--skip-enable-duplicates	skip_enable_duplicate_keywords	Пропускать ключевое слово, которое уже существует в целевой группе объявлений, вместо его активации. Только для правил поисковых запросов
--pause-original	pause_in_original_ad_group	Приостановить исходное ключевое слово в его группе объявлений. Только для правил ключевых слов

--cpt-bid-type и --match-type не имеют значений по умолчанию, поэтому оба обязательны, если файл правила не содержит собственных params.

Четыре флага зависят от поля operate_with правила: --negate, --no-negate и --skip-enable-duplicates относятся к правилу search-term, --pause-original — к правилу targeting-keyword. Флаг из другого набора завершается с кодом выхода 2 и выводит список применимых флагов.

adapty asa automations list

Список правил автоматизации. Поле status принимает значение 1 для активных и 0 для остановленных.

adapty asa automations list

Принимает флаги пагинации.

adapty asa automations get

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

adapty asa automations get <automation-id>

Argument	Description
automation-id	Automation rule ID (UUID)

adapty asa automations create

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

adapty asa automations create --file rule.json

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

--file обязателен, и файл должен содержать ровно одно действие: API хранит одно действие и одно условие на правило.

Также принимает флаги действия add-as-keyword, которые заполняют или переопределяют actions[0].params:

adapty asa automations create --file rule.json --target-ad-group <ad-group-id> --match-type EXACT --cpt-bid-type search_term_current_cpt --negate ad-group

adapty asa automations update

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

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

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

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

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

Также принимает флаги действия add-as-keyword. Передача одного из них превращает вызов в операцию чтение-изменение-запись: CLI читает правило, перестраивает actions[0].params и отправляет весь список actions обратно, поскольку API заменяет actions целиком, а не объединяет с существующим. Правки, сделанные в дашборде между чтением и записью, будут перезаписаны.

An update with an action flag also repairs a rule whose stored params carry the shape of another action. The params are rebuilt from scratch, so only the stored keys that fit add-as-keyword-to are kept and everything else has to come from a flag.

adapty asa automations run

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

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

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

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

Запуск ставится в очередь, и команда выводит ID запуска. Просмотреть результат можно с помощью automations runs.

adapty asa automations runs

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

adapty asa automations runs <automation-id>

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

Принимает флаги пагинации.

Метрики

adapty asa metrics

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

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	Да	Название метрики, можно указывать несколько раз
--app	Нет	Фильтровать только по этим приложениям. Можно указывать несколько раз
--campaign	Нет	Фильтровать только по этим кампаниям. Можно указывать несколько раз
--ad-group	Нет	Фильтровать только по этим группам объявлений. Можно указывать несколько раз
--group-by	Нет	Группировка строк по country, day, week, month, quarter или year. Можно указывать несколько раз
--by-days	Нет	Окно продления в днях для метрик когорт, можно указывать несколько раз. Максимум 16 за вызов. Если не указать — используются значения по умолчанию из дашборда
--order-by	Нет	Метрика или поле для сортировки
--order-by-day	Нет	Ранжировать по метрике когорты при данном окне продления. Должно быть одним из значений --by-days
--order	Нет	asc или desc. По умолчанию: desc

Принимает флаги пагинации. Из фильтров списка поддерживает только --app, --campaign и --ad-group; параметров --search и --status нет. Чтобы сузить отчёт по другим критериям, сопоставьте строки с идентификаторами из команды list с нужной областью.

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

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. Полный список и описание расчёта каждой метрики см. в разделе Метрики. Если указать несуществующее название, команда завершится с ошибкой и выведет список допустимых значений.

При использовании --entity keyword параметр --metric также принимает метрики, доступные только для ключевых слов. Apple сообщает долю показов и позицию как для любой позиции объявления, так и для первой позиции объявления, поэтому каждая из них представлена в двух вариантах: _all и _first. Подробнее о том, как Apple их определяет, см. в разделе Insights.

Метрика	Значение
impression_midpoint_all, impression_midpoint_first	Доля показов за отчётный период, в процентах
rank_all, rank_first	Позиция вашего приложения среди других приложений по ключевому слову. Актуальное значение, независимо от --date-from и --date-to
search_popularity	Популярность поискового запроса от 1 до 5

Ключевое слово без данных отчёта возвращает 0 для этих метрик. Начиная с CLI 0.9.2, эти названия заменяют rank и impression_midpoint.

Каждая метрика вычисляется по всему уровню сущности до разбивки на страницы, поэтому запрашивайте только нужные столбцы, а не весь каталог. subscribers и paid_subscribers считают уникальные профили на сущность — это примерно в семнадцать раз дороже простого запроса расходов и установок; то же касается arppu и arpas, которые производятся от них. На любом --entity эти четыре имени требуют --campaign или --ad-group для сужения запроса:

adapty asa metrics --entity keyword --date-from 2026-07-01 --date-to 2026-07-31 --metric arpas --campaign <campaign-id>

Без одного из этих двух фильтров запрос завершается ошибкой 422 cli_metric_scope_too_wide. Сужение области — самый дешёвый способ ускорить любой запрос метрик, поскольку стоимость определяется количеством агрегируемых сущностей, а не размером страницы.

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

Наименьшее значение --group-by	Максимальный период
day	28 дней
Без группировки по периоду	90 дней
week	180 дней
month и крупнее	365 дней

Гранулярность по дням охватывает не более четырёх недель. Для более длительного периода запрашивайте данные с гранулярностью week — один запрос вмещает до полугода.

Каждая страница также ограничена 5000 строк разбивки, где строка — это одна сущность × страна × период. Если страница превышает лимит, запрос завершается ошибкой 422 cli_response_too_large. Уменьшите детализацию группировки, сузьте временной диапазон или снизьте значение --page-size. При группировке по day ошибка сообщает подходящий размер страницы — используйте именно его, а не вычисляйте самостоятельно. Команда metrics overview не возвращает разбивку по сущностям, поэтому это ограничение к ней не применяется.

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

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.

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 дней

Конкуренты

adapty asa competitors summary

Показывает сводку по ключевым словам Apple Ads, на которые делает ставки набор приложений из App Store. Возвращает те же данные о конкурентах, что и Market Intelligence в дашборде.

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

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

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

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

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

История изменений

История изменений поступает напрямую из Apple Ads API. Adapty её не хранит, а Apple держит её в течение 6 месяцев. Она охватывает все изменения в организации, включая изменения, внесённые непосредственно в Apple Ads, через поддержку Apple или другие инструменты API.

adapty asa change-history list

Список изменений в одной организации Apple Ads, начиная с самых новых.

adapty asa change-history list --campaign-group <campaign-group-id> --date-from 2026-10-01 --entity-type Campaign --event-type UPDATE

Флаг	Обязателен	Описание
--campaign-group	Да	Организация для чтения (UUID из orgs list). Одна организация за вызов. Чтобы прочитать несколько, запустите команду для каждой
--date-from	Нет	Начало периода (YYYY-MM-DD). По умолчанию: 7 дней назад
--date-to	Нет	Конец периода (YYYY-MM-DD). По умолчанию: сегодня. Период не может превышать 14 дней
--entity-type	Нет	Campaign, AdGroup, Keyword, NegativeKeyword, Ad, Creative, LocationGroup, Org или AdAccount. Можно указывать несколько раз. По умолчанию: все типы, кроме Org и AdAccount. Org и AdAccount нельзя комбинировать с другими типами
--event-type	Нет	CREATE, UPDATE или DELETE. Можно указывать несколько раз
--user-type	Нет	Кто внёс изменение: CUSTOMER (в Apple Ads), CUSTOMER_API (через Apple Ads API) или APPLE_SUPPORT. Можно указывать несколько раз
--campaign, --ad-group, --entity-id	Нет	Числовые ID Apple для кампании, группы объявлений или изменённой сущности. Можно указывать несколько раз
--user	Нет	Apple ID пользователя, внёсшего изменение. Можно указывать несколько раз
--txn	Нет	ID транзакции Apple. Можно указывать несколько раз
--fields	Нет	Разворачивает каждое изменение в одну строку на каждое изменённое поле с его старым и новым значением

Каждая строка — одна транзакция: кто её совершил (modified_by, user_type), когда (event_time) и какие сущности были изменены. Каждая сущность содержит detail_id для change-history get.

С --fields размер страницы по умолчанию равен 10, а большее значение --page-size не принимается. Страница, для которой потребовалось бы более 20 запросов, завершится ошибкой: сузьте фильтры, или уберите --fields и читайте отдельные изменения с помощью change-history get.

Принимает флаги пагинации. Произведение --page × --page-size не может превышать 1000.

adapty asa change-history get

Показывает изменения на уровне полей для одной сущности в одной транзакции.

adapty asa change-history get Campaign.444555666.TXN_ID --campaign-group <campaign-group-id>

Аргумент	Описание
detail-id	detail_id из change-history list, в формате EntityType.entityId.txnId

Флаг	Обязательный	Описание
--campaign-group	Да	Организация, к которой относится изменение. Берётся из campaign_group_id в строке списка

Ответ содержит список каждого изменённого поля с его old_values и new_values, а также метаданные сущности в entity_metadata. Запрос с detail_id, о котором у Apple нет сведений, возвращает 404.

Ошибки

Статус	Код	Описание
402	ads_manager_subscription_required	У компании нет активной подписки Ads Manager
403	cli_ad_account_unreadable	change-history не может прочитать организацию: токен Apple Ads отозван, организация больше не привязана или Apple отклонила доступ
404	—	Сущность не существует или принадлежит другой компании
409	cli_idempotency_in_progress	Запись с тем же ключом идемпотентности ещё выполняется
422	cli_idempotency_key_reuse	Тот же ключ идемпотентности был использован с другим телом запроса
422	cli_metric_scope_too_wide	Запрошена метрика подсчёта профилей без --campaign или --ad-group
422	cli_response_too_large	Страница metrics превысила бы 5000 строк разбивки
429	cli_analytics_busy	Пул аналитики занят или для компании ещё выполняется сборка пула ключевых слов. Время ожидания указано в заголовке Retry-After
429	cli_cooldown_active	Слишком большое количество отклонённых запросов перевело токен в режим ожидания
429	cli_upstream_rate_limited	Apple ограничила частоту запросов change-history. Время ожидания от Apple указано в заголовке Retry-After
504	cli_read_timeout	Запрос change-history выполнялся дольше 50 секунд. Сузьте период или фильтры

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

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