Эксперименты - Console API

Получение списка, создание, чтение и обновление эксперимента. Console API авторизует запрос по OAuth2-scope (см. Авторизацию).

к сведению

Интерактивный контракт с try-it-out - в Справочнике API (Swagger). Пошаговый сценарий интеграции - в сквозном сценарии.

Создание эксперимента

Требуемый scope - edit:experiment:create_experiments.

Эндпоинт	Что делает
`POST /experiments/v1`	Создаёт эксперимент и возвращает его `id`. Эксперимент появляется в статусе черновика - для запуска вызовите start.

Как создать эксперимент

Получите допустимые значения из справочников - команды, типы участников, списки участников, пресеты метрик. Имена в теле запроса должны совпадать со значениями из справочников.
Соберите тело запроса: обязательные поля и, при необходимости, метрики, сегменты, блок retro или switchback. Полный список полей - в таблице Поля запроса.
Отправьте POST /experiments/v1 с телом в формате JSON.
Сохраните id из ответа - он нужен для запуска, обновления и остановки эксперимента.
Запустите эксперимент методом start.

Тело запроса

ConsoleCreateExperimentRequest - схема тела запроса (JSON). Ниже перечислены все поля с типами и обязательностью.

Где смотреть детали:

Полный машинный контракт и примеры - в Справочнике API (Swagger).
Структура вложенных объектов (groups, segments, метрики, retro, switchback) - в Вложенных объектах ниже.

Поля запроса

Параметр	Тип	Обязательность	Описание
`title`	`string`	Да	Название эксперимента.
`label`	`string`	Да	Уникальный текстовый идентификатор эксперимента (например, `new_checkout_flow`). В отличие от `title`, задаёт машинно-удобный ключ, а не отображаемое название.
`participantType`	`string`	Да	Label типа участника из справочника participantTypes.
`groups`	`ConsoleExperimentGroupIn[]`	Да	Список групп эксперимента.
`team`	`string`	Да	Команда-владелец из справочника teams.
`metricPresets`	`string[]`	Да	Пресеты метрик из справочника preset-names.
`duration`	`integer`	Условно	Плановая длительность A/B-фазы в днях. Обязательно для `regular` и `switchback`.
`retro`	`ConsoleRetroIn`	Условно	Параметры ретро-эксперимента. Обязательно для `type = "retro"`.
`switchback`	`ConsoleSwitchbackIn`	Условно	Параметры switchback-эксперимента. Обязательно для `type = "switchback"`.
`propagateExposureDays`	`integer`	Условно	Число дней запоминания exposure. Обязательно при `exposure = "days"`.
`type`	`enum ExperimentType`	Нет	Тип эксперимента. По умолчанию `"regular"`.
`statisticalMethod`	`enum StatisticsMethod`	Нет	Метод агрегации метрик. По умолчанию `"frequentist"`.
`exposure`	`enum ConsoleExposureType`	Нет	Режим учёта exposure (`all` / `days`). По умолчанию `"all"`.
`markupScopeType`	`enum ExperimentMarkupScopeType`	Нет	Тип разметки: `incoming_traffic`, `event`, `segment`.
`allocationTraffic`	`number`	Нет	Доля трафика эксперимента в процентах.
`segments`	`ConsoleExperimentSegmentIn[]`	Нет	Сегменты таргетинга.
`comparisons`	`ConsoleExperimentComparisonIn[]`	Нет	Пары групп для сравнения. Если не заданы - строятся автоматически.
`goalMetrics`	`ConsoleGoalMetricIn[]`	Нет	Целевые метрики.
`counterMetrics`	`ConsoleCounterMetricIn[]`	Нет	Контрольные (guardrail) метрики.
`layer`	`string`	Нет	Название слоя.
`useHoldout`	`string`	Нет	Название holdout-группы.
`allowedUsers`	`string[]`	Нет	Принудительно включённые пользователи.
`excludedUsers`	`string[]`	Нет	Исключённые пользователи.
`tags`	`string[]`	Нет	Теги эксперимента.
`description`	`string`	Нет	Описание эксперимента.
`issueUrl`	`string`	Нет	Ссылка на задачу.
`startTime`	`string`	Нет	Плановое время старта эксперимента.
`cutFirstDayOffset`	`boolean`	Нет	Обрезать первый неполный день.
`experimentOffsets`	`integer[]`	Нет	Дополнительные смещения в днях.
`aggregationWindows`	`integer[]`	Нет	Скользящие окна агрегации.
`expectedExposurePlace`	`string`	Нет	Место или событие ожидаемой экспозиции.
`keepMarkingOnStop`	`boolean`	Нет	Сохранять marking при остановке.

ExperimentType, StatisticsMethod, ConsoleExposureType, ExperimentMarkupScopeType - справочники значений в Перечислениях.

Лишние поля в теле запроса отклоняются

Схема запроса использует extra=forbid. Любое поле сверх описанных приводит к ошибке валидации. Проверяйте написание имён полей перед отправкой.

Условная обязательность полей

Часть полей обязательна в зависимости от типа эксперимента и модели экспозиции:

Условие	Обязательное поле	Сообщение об ошибке
`type = "retro"`	`retro`	`retro is required for retro experiments`
`type = "switchback"`	`switchback`	`switchback is required for switchback experiments`
`type` = `regular` / `switchback`	`duration`	`duration is required for regular and switchback experiments`
`exposure = "days"`	`propagateExposureDays`	`propagateExposureDays is required when exposure=days`

Вложенные объекты

Группа (ConsoleExperimentGroupIn):

Параметр	Тип	Обязательность	Пример	Описание
`name`	`string`	Да	`"control"`	Имя группы.
`isControl`	`bool`	Да	`true`	Признак контрольной группы.
`weight`	`float`	Нет	`50`	Вес группы. Если не задан, распределяется равномерно.
`description`	`string`	Нет	`"baseline"`	Описание группы.
`allowedUsers`	`list`	Нет	-	Пользователи, допущенные в группу.

Сравнение (ConsoleExperimentComparisonIn):

Параметр	Тип	Обязательность	Пример	Описание
`control`	`string`	Да	`"control"`	Лейбл контрольной группы.
`test`	`string`	Да	`"test"`	Лейбл тестовой группы.

Сегмент (ConsoleExperimentSegmentIn) и условие (ConsoleExperimentConditionIn). Сегмент содержит список условий conditions, условия внутри сегмента объединяются логикой AND:

Параметр	Тип	Обязательность	Пример	Описание
`param`	`string`	Да	`"platform"`	Лейбл контекст-параметра.
`predicate`	`string`	Да	`"eq"`	Оператор сравнения.
`value`	`string \| list \| int \| float \| bool`	Да	`"android"`	Значение для сравнения.

Целевая метрика (ConsoleGoalMetricIn) и контрольная метрика (ConsoleCounterMetricIn):

Параметр	Тип	Обязательность	Описание
`name`	`string`	Да	Имя метрики из справочника objective-meta.
`breakdown`	`string`	Нет	Срез метрики.
`expectedEffect`	`float`	Нет	Ожидаемый эффект (только для `ConsoleGoalMetricIn`).
`maxDeviation`	`float`	Нет	Допустимое отклонение (только для `ConsoleCounterMetricIn`).

Объект retro (ConsoleRetroIn)

Объект обязателен для экспериментов с type = "retro".

Параметр	Тип	Обязательность	Пример	Описание
`type`	`enum RetroType`	Да	`"parent_experiment"`	Тип ретро-эксперимента.
`startDate`	`date`	Да	`"2026-06-01"`	Дата начала.
`endDate`	`date`	Да	`"2026-06-15"`	Дата окончания. Должна быть в прошлом.
`parentExperimentId`	`int \| null`	Условно	`123`	ID родительского эксперимента.

RetroType - справочник значений в Перечислениях.

Объект retro проходит следующие валидации:

Условие	Требование	Сообщение об ошибке
`type = "parent_experiment"`	`parentExperimentId` обязателен	`retro.parentExperimentId is required for parent_experiment`
`type` не `parent_experiment`	`parentExperimentId` запрещён	`retro.parentExperimentId is allowed only for parent_experiment`
`endDate` не в прошлом	дата должна быть в прошлом	`retro.endDate must be in the past`

Объект switchback (ConsoleSwitchbackIn)

Объект обязателен для экспериментов с type = "switchback". Все поля обязательны.

Параметр	Тип	Обязательность	Пример	Описание
`clusterIdSetNames`	`list`	Да	-	Имена наборов идентификаторов кластеров.
`clusterPercent`	`float`	Да	`50`	Процент кластеров (0-100).
`windowSizeMinutes`	`int > 0`	Да	`60`	Размер окна в минутах.
`burnInMinutes`	`int >= 0`	Да	`5`	Прогрев в минутах.
`burnOutMinutes`	`int >= 0`	Да	`5`	Остывание в минутах.
`strategy`	`enum SwitchbackStrategy`	Да	`"DETERMINISTIC_RANDOM"`	Стратегия распределения.

SwitchbackStrategy - справочник значений в Перечислениях.

Switchback - прогрев и остывание

Прогрев и остывание не должны заполнять всё окно. Сумма burnInMinutes + burnOutMinutes должна быть строго меньше windowSizeMinutes. Иначе запрос отклоняется с ошибкой burnInMinutes + burnOutMinutes must be less than windowSizeMinutes.

Автоматическое поведение

Если вы не передаёте comparisons, Console API строит их автоматически: находит единственную контрольную группу (isControl) и сравнивает с ней каждую тестовую. Отсутствие контрольной группы даёт ошибку MISSING_CONTROL_GROUP, наличие более одной - DUPLICATE_CONTROL_GROUP.

Если вы не задаёте weight, Console API распределяет вес равномерно: 100 // N на каждую из N групп, остаток добавляет к первым группам.

Формирование запроса

URL:

POST https://<host>/experiments/v1

Заголовки:

Authorization: Bearer <ваш_токен>
Content-Type: application/json

Тело запроса:

{
  "title": "Новый флоу оформления",
  "label": "new_checkout_flow",
  "type": "regular",
  "participantType": "user_id",
  "team": "checkout",
  "duration": 14,
  "metricPresets": ["core_metrics"],
  "groups": [
    { "name": "control", "isControl": true },
    { "name": "test", "isControl": false }
  ]
}

Пример успешного ответа:

{
  "result": {
    "id": 12345
  }
}

Расшифровка ответа:

Параметр	Тип	Пример	Описание
`id`	`int`	`12345`	Идентификатор созданного эксперимента.

Чтение

Требуемый scope - read:experiment:read_experiments.

Эндпоинт	Что возвращает
`GET /experiments/v1`	Список экспериментов. Фильтры: `statuses`, `tags`, `query`; пагинация: `page`, `pageLimit`.
`GET /experiments/v1/{id}`	Полную конфигурацию одного эксперимента по `id`.

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

Обновление эксперимента

Требуемый scope - edit:experiment:update_experiments.

Эндпоинт	Что делает
`PATCH /experiments/v1/{id}`	Частично обновляет эксперимент. Тело запроса - `ConsoleUpdateExperimentRequest`, ответ - `{ok: true}`.

Все поля тела - опциональные, обязательных полей нет. Набор полей совпадает с полями создания. Схема использует extra=forbid.

Условная обязательность при обновлении:

Условие	Требование
`type = "retro"`	требуется `retro`
`type = "switchback"`	требуется `switchback`
`exposure = "days"`	требуется `propagateExposureDays`

к сведению

В отличие от создания, обновление не требует duration для regular- и switchback-экспериментов.

Ограничения после запуска. У запущенного эксперимента (статус In progress) часть полей конфигурации становится недоступной для изменения. Точный перечень заблокированных полей возвращается в ошибке 400 при попытке их изменить.

Пример правки описания и тегов:

{
  "description": "Обновлённое описание",
  "tags": ["integration", "updated"]
}

Формат ответа и ошибок

Console API возвращает успешный ответ (200) в конверте {result: <schema>}, а ошибку - в конверте {error: SanitizedErrorBody}. Формат общий для всех методов раздела.

Тело ошибки SanitizedErrorBody содержит три обязательных поля:

Параметр	Тип	Пример	Описание
`code`	`string`	`"validation_error"`	Машиночитаемый код ошибки.
`message`	`string`	`"duration is required"`	Текстовое описание ошибки.
`request_id`	`string \| null`	`"a1b2c3d4"`	Идентификатор запроса для диагностики.

Документированные статусы ответа:

Статус	Значение
`200`	Успешный ответ.
`400`	Ошибка валидации тела запроса.
`401`	Запрос не авторизован.
`403`	Недостаточно прав (scope).
`404`	Эксперимент не найден.
`500`	Внутренняя ошибка сервера.

Создание эксперимента​

Как создать эксперимент​

Тело запроса​

Поля запроса​

Условная обязательность полей​

Вложенные объекты​

Объект retro (ConsoleRetroIn)​

Объект switchback (ConsoleSwitchbackIn)​

Автоматическое поведение​

Формирование запроса​

Чтение​

Обновление эксперимента​

Формат ответа и ошибок​