Показывает, подключены ли Яндекс Аудитории: есть ли токен, откуда он взят (переменная окружения YANDEX_AUDIENCE_TOKEN или сохранённый вход), когда истекает и где лежит файл с сохранёнными данными. Ничего не отправляет в сеть и не показывает сам токен. Вызовите это, если инструменты Аудиторий отвечают, что подключение не настроено.

Первый шаг подключения Яндекс Аудиторий без правки конфигурации и без перезапуска клиента. Возвращает ссылку на страницу Яндекс OAuth. Покажите ссылку пользователю целиком и попросите: открыть её в браузере под аккаунтом Яндекса, которому принадлежат нужные сегменты (или которому они доверены), подтвердить доступ на чтение и изменение сегментов и прислать показанный код подтверждения. Полученный код передайте в finish_login. Код действует 10 минут. Сам по себе код бесполезен для постороннего: обменять его может только этот сервер.

Второй шаг подключения: обменивает код подтверждения из start_login на токен доступа, сохраняет его в файл только для владельца (0600) и сразу проверяет живым запросом к Аудиториям. После успеха остальные инструменты работают немедленно — перезапускать клиент не нужно. Код одноразовый и живёт 10 минут: если он не принят, вызовите start_login заново и попросите свежий.

Удаляет сохранённый токен Аудиторий с диска. Токен, заданный переменной окружения YANDEX_AUDIENCE_TOKEN, не трогает — его нужно убирать из конфигурации клиента вручную. Доступ, выданный приложению, остаётся активным на стороне Яндекса: отозвать его можно в Яндекс ID.

Возвращает список сегментов Яндекс Аудиторий, доступных пользователю (все типы: uploading, metrika, appmetrica, lookalike, geo, pixel). Ответ — {"segments": [...]}: у каждого сегмента id, name, type, status (uploaded | is_processed | processed | processing_failed | is_updated | few_data), create_time, owner и типоспецифичные поля (у файловых — content_type, hashed, item_quantity, matched_quantity и др.). Пагинация: limit (по умолчанию 10000) и offset; параметр pixel фильтрует по сегментам, созданным на основе указанного пикселя. Отдельного метода получения одного сегмента в API нет — фильтруйте этот список по id.

Создаёт сегмент из TSV/TXT-файла с данными: идентификаторы устройств (IDFA/GAID), MAC-адреса или SHA256-хеши, по одной записи в строке; минимум 100 записей, до 1 ГБ, UTF-8. Это первый шаг двухфазного создания: в ответе сегмент со статусом uploaded и его id — затем сегмент нужно сохранить инструментом confirm_segment (имя, тип содержимого, хеширование). Источник данных: file_path (путь к локальному файлу) или content (содержимое строкой) — ровно одно из двух. Квота на создание сегментов: 10/мин, 100/час, 500/сутки.

Создаёт сегмент из CSV-файла с CRM-данными. Первая строка — заголовок: колонки email, phone, ext_id (или external_id) и произвольные дополнительные поля; минимум 100 записей, до 1 ГБ. Это первый шаг двухфазного создания: в ответе сегмент со статусом uploaded и его id — затем сегмент нужно сохранить инструментом confirm_segment (content_type: crm). Источник данных: file_path (путь к локальному файлу) или content (содержимое строкой) — ровно одно из двух. Квота на создание сегментов: 10/мин, 100/час, 500/сутки.

Сохраняет сегмент, созданный из файла (второй шаг после upload_segment_file / upload_segment_csv_file): задаёт имя, тип содержимого и параметры хеширования. content_type: idfa_gaid (идентификаторы мобильных устройств), mac (MAC-адреса) или crm (CSV с CRM-данными). hashing_alg — только SHA256 (MD5 не поддерживается API с 01.01.2025). device_matching_type: CROSS_DEVICE (по умолчанию) или IN_DEVICE (только для idfa_gaid). check_size=false позволяет сохранить сегмент меньше 100 записей (его нельзя использовать в Директе, пока размер не превысит 100). Ответ — {"segment": {...}}; обработка занимает время, статус смотрите через list_segments.

Изменяет сегмент. В схеме изменения доступно только поле name, так что фактически это переименование. Работает с сегментом любого типа; ответ — {"segment": {...}} с обновлёнными данными.

Удаляет указанный сегмент Яндекс Аудиторий. Операция необратима (метода восстановления сегмента в API нет). Успешный ответ — {"success": true}.

Создаёт сегмент типа lookalike — пользователи, «похожие» по поведению в интернете на аудиторию исходного сегмента (lookalike_link). lookalike_value — степень похожести от 1 (максимальная точность, меньший охват) до 5 (максимальный охват). maintain_device_distribution / maintain_geo_distribution (по умолчанию true) сохраняют распределение по типам устройств и городам исходного сегмента. Ответ — {"segment": {...}}; сегмент обрабатывается асинхронно, статус смотрите через list_segments. Квота: 10/мин, 100/час, 500/сутки.

Создаёт сегмент типа pixel — пользователи, которых пиксель (pixel_id из list_pixels) видел за последние period_length дней (1..90). Дополнительные условия объединяются по «И»: частота показов (times_quantity + times_quantity_operation: lt | eq | gt) и фильтры по UTM-меткам (utm_source, utm_medium, utm_campaign, utm_content, utm_term). device_matching_type присутствует в примере запроса API, но не описан в документации — считайте экспериментальным. Ответ — {"segment": {...}}. Квота: 10/мин, 100/час, 500/сутки.

Возвращает список пикселей Яндекс Аудиторий пользователя. Ответ — {"pixels": [...]}: у каждого пикселя id, name, create_time, url (код пикселя для вставки в рекламные материалы), охваты user_quantity_7 / user_quantity_30 / user_quantity_90 (уникальные пользователи за 7/30/90 дней) и segments — сегменты, построенные на этом пикселе.

Создаёт пиксель Яндекс Аудиторий с заданным именем. В ответе — {"pixel": {...}} с полем url: код пикселя, который нужно вставить в рекламные материалы (баннеры), после чего на его основе можно строить сегменты инструментом create_pixel_segment.

Изменяет указанный пиксель (в схеме изменения доступно только поле name — переименование). Ответ — {"pixel": {...}} с обновлёнными данными.

Удаляет указанный пиксель Яндекс Аудиторий. Успешный ответ — {"success": true}. В API существует метод восстановления удалённого пикселя (POST /v1/management/pixel/{id}/undelete) — при необходимости он доступен через raw_request.

Возвращает список разрешений на управление сегментом. Ответ — {"grants": [...]}: у каждого разрешения user_login (логин пользователя), permission (edit — редактирование, view — просмотр), comment и created_at.

Создаёт разрешение на управление сегментом для указанного логина Яндекса. permission: edit — редактирование и использование сегмента, view — только просмотр/использование. Ответ — {"grant": {...}} (поле created_at заполняет сервер).

Удаляет разрешение на управление сегментом у указанного пользователя. Успешный ответ — {"success": true}.

Escape hatch: прямой вызов любого пути Yandex Audience API, для эндпоинтов без выделенного инструмента (например, PUT "v1/management/segment/{id}/reprocess" — пересчёт сегмента, или POST "v1/management/pixel/{id}/undelete" — восстановление пикселя). Путь указывается относительно хоста API; query-параметры включайте прямо в path (например, "v1/management/segments?limit=5"). body отправляется как JSON для POST/PUT. Заголовок Authorization подставляется автоматически; путь на чужой хост будет отклонён.