Обновлено: 18.08.2026

Сегментация аудитории

Именованные группы пользователей по условиям — истории покупок, посещаемости, статусу лояльности. Сегмент собирается один раз и переиспользуется в рассылках и экспортах.

Обзор методов

Метод	Путь	Описание
`GET`	`/segments`	Список сегментов
`POST`	`/segments`	Создать сегмент
`GET`	`/segments/{id}/users`	Пользователи в сегменте
`PATCH`	`/segments/{id}`	Изменить условия сегмента
`DELETE`	`/segments/{id}`	Удалить сегмент
`POST`	`/segments/preview`	Предпросмотр размера аудитории

Список сегментов

Эндпоинт

GET /segments

Все сегменты клуба с текущим размером аудитории.

Запрос

curl https://api.virazh.io/v1/segments \
  -H "Authorization: Bearer sk_test_51H..."

Ответ

{
  "data": [
    { "id": "seg_active_fans", "name": "Активные болельщики", "size": 4380 },
    { "id": "seg_gold_tier", "name": "Gold-уровень", "size": 612 }
  ]
}

Поля ответа

Поле	Тип	Описание
`data`	`array<Segment>`	Сегменты с полями id, name, size.

Создать сегмент

Эндпоинт

POST /segments

Собирает сегмент по условиям — сочетание фильтров по покупкам, посещаемости и статусу лояльности.

Параметры

Параметр	Где	Тип	Обязателен	Описание
`name`	`тело`	string	да	Название сегмента.
`conditions`	`тело`	array<Condition>	да	Условия отбора: { field, op, value }. Складываются по И.

Запрос

curl https://api.virazh.io/v1/segments \
  -X POST \
  -H "Authorization: Bearer sk_test_51H..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Не продлившие абонемент",
    "conditions": [
      { "field": "subscription_status", "op": "eq", "value": "expired" }
    ]
  }'

Ответ

{
  "id": "seg_lapsed_1a",
  "name": "Не продлившие абонемент",
  "size": 892
}

Поля ответа

Поле	Тип	Описание
`id`	`string`	Идентификатор созданного сегмента.
`name`	`string`	Название сегмента.
`size`	`integer`	Размер аудитории на момент создания.

Пользователи в сегменте

Эндпоинт

GET /segments/{id}/users

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

Параметры

Параметр	Где	Тип	Обязателен	Описание
`id`	`путь`	string	да	Идентификатор сегмента.
`limit`	`query`	integer	нет	Размер страницы, до 100.

Запрос

curl "https://api.virazh.io/v1/segments/seg_active_fans/users?limit=50" \
  -H "Authorization: Bearer sk_test_51H..."

Ответ

{
  "segment_id": "seg_active_fans",
  "total": 4380,
  "users": [
    { "id": "usr_8f21c", "name": "Иван Петров" },
    { "id": "usr_71bd0", "name": "Мария Орлова" }
  ]
}

Поля ответа

Поле	Тип	Описание
`segment_id`	`string`	Идентификатор сегмента.
`total`	`integer`	Общий размер аудитории сегмента.
`users`	`array<UserRef>`	Пользователи на текущей странице с полями id, name.

Изменить условия сегмента

Эндпоинт

PATCH /segments/{id}

Обновляет название или набор условий существующего сегмента. Размер аудитории пересчитывается сразу после сохранения.

Параметры

Параметр	Где	Тип	Обязателен	Описание
`id`	`путь`	string	да	Идентификатор сегмента.
`name`	`тело`	string	нет	Новое название.
`conditions`	`тело`	array<Condition>	нет	Новый набор условий, полностью заменяет старый.

Запрос

curl https://api.virazh.io/v1/segments/seg_lapsed_1a \
  -X PATCH \
  -H "Authorization: Bearer sk_test_51H..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Не продлившие абонемент (30+ дней)" }'

Ответ

{
  "id": "seg_lapsed_1a",
  "name": "Не продлившие абонемент (30+ дней)",
  "size": 754
}

Поля ответа

Поле	Тип	Описание
`id`	`string`	Идентификатор сегмента.
`name`	`string`	Актуальное название.
`size`	`integer`	Размер аудитории после пересчёта.

Удалить сегмент

Эндпоинт

DELETE /segments/{id}

Удаляет сегмент. Рассылки, уже запущенные по этому сегменту, не затрагиваются — удаляется только сохранённое определение.

Параметры

Параметр	Где	Тип	Обязателен	Описание
`id`	`путь`	string	да	Идентификатор сегмента.

Запрос

curl https://api.virazh.io/v1/segments/seg_lapsed_1a \
  -X DELETE \
  -H "Authorization: Bearer sk_test_51H..."

Ответ

{
  "id": "seg_lapsed_1a",
  "status": "deleted"
}

Поля ответа

Поле	Тип	Описание
`id`	`string`	Идентификатор удалённого сегмента.
`status`	`string`	deleted при успешном удалении.

Предпросмотр размера аудитории

Эндпоинт

POST /segments/preview

Считает, сколько пользователей попадёт под условия, без сохранения сегмента — удобно для подбора фильтров в интерфейсе перед созданием.

Параметры

Параметр	Где	Тип	Обязателен	Описание
`conditions`	`тело`	array<Condition>	да	Условия отбора в том же формате, что и при создании сегмента.

Запрос

curl https://api.virazh.io/v1/segments/preview \
  -X POST \
  -H "Authorization: Bearer sk_test_51H..." \
  -H "Content-Type: application/json" \
  -d '{ "conditions": [{ "field": "loyalty_status", "op": "eq", "value": "gold" }] }'

Ответ

{
  "estimated_size": 612
}

Поля ответа

Поле	Тип	Описание
`estimated_size`	`integer`	Оценка размера аудитории по переданным условиям.

Полезно знать

Размер сегмента (size) в списке — снэпшот на момент последнего пересчёта, а не live-значение: для точных чисел запрашивайте /segments/{id}/users с пустым limit=0.
Условия сегмента складываются по И (AND) — для ИЛИ создайте несколько сегментов и объединяйте на своей стороне.
Сегмент, использованный в рассылке или экспорте, можно свободно редактировать — исторические задачи хранят снимок аудитории на момент запуска, а не ссылку на текущий сегмент.
Перед сохранением сложного сегмента используйте /segments/preview — метод считает estimated_size по тем же условиям, но не создаёт объект, удобно для интерфейса с живым предпросмотром.

Документация «Вираж»

Сегментация аудитории

Обзор методов

Список сегментов

Создать сегмент

Пользователи в сегменте

Изменить условия сегмента

Удалить сегмент

Предпросмотр размера аудитории

Полезно знать