API: Segments

Project-scoped saved, dynamic filter rules. Segments never materialize actor ids; `segment:{id}` references are resolved live for every query.

Кому: Разработчики, интегрирующие ActionPulse по HTTP
Проверено: 28.07.2026

На этой странице

GET /projects/{id}/segments
POST /projects/{id}/segments
GET /projects/{id}/segments/{sid}
PATCH /projects/{id}/segments/{sid}
DELETE /projects/{id}/segments/{sid}

Раздел собран из спецификации OpenAPI продукта: 5 метод(ов). Поверхность — query-api (основной API, база /api/v1). Все методы требуют аутентификации.

Методы раздела

GET /projects/{id}/segments
POST /projects/{id}/segments
GET /projects/{id}/segments/{sid}
PATCH /projects/{id}/segments/{sid}
DELETE /projects/{id}/segments/{sid}

GET /projects/{id}/segments

List saved segments in a project

Аутентификация: Bearer: токен доступа (JWT)
operationId: getProjectsIdSegments

Cloud requires the Growth or Scale saved_segments entitlement; on-prem requires saved_segments in the current verified signed-license feature subset. Newest first. `cursor` is an opaque keyset cursor over `(created_at,id)`; segment definitions contain rules, never actor ids.

Параметры

Имя	Где	Тип	Описание
`id` обязателен	Путь	`integer (int32)`	Project id.
`cursor` необязателен	Query	`string`
`limit` необязателен	Query	`integer`	По умолчанию `50`.

Ответы

Код	Что означает	Тело
200	Segments page	`object`
401	Missing or invalid credentials (code=unauthorized)	`Error`
402	Product access is not active. `code=trial_expired` means the organization's trial ended without payment; `code=subscription_required` means there is no current paid subscription or live trial. In both cases ingest, mutations and plan-gated read/write capabilities are paused until a plan is paid; details.billing_url, when present, points to the cabinet billing page.	`Error`
403	Authenticated but not permitted (code=forbidden)	`Error`
404	Resource not found (code=not_found)	`Error`
422	Request failed validation (code=validation_failed)	`Error`

POST /projects/{id}/segments

Create a saved segment (analyst+)

Аутентификация: Bearer: токен доступа (JWT)
operationId: postProjectsIdSegments

Cloud requires the Growth or Scale saved_segments entitlement; on-prem requires saved_segments in the current verified signed-license feature subset. References are validated in the same project and checked for cycles and expansion limits before the rule is stored.

Параметры

Имя	Где	Тип	Описание
`id` обязателен	Путь	`integer (int32)`	Project id.

Тело запроса application/json , обязательно

Поле	Тип	Описание
`name` обязательно	`string`
`filters` обязательно	`SegmentDefinition`	Versioned rule. `filters` are ANDed. With `performed` or `not_performed`, predicates apply to the tested event and membership is actor-level. Exact report-derived membership is stored in `source`; actor ids are forbidden. `performed`, `not_performed`, and `source` are mutually exclusive in v1; a source rule requires top-level `filters: []` because its own report filters are captured inside the source branch.

Ответы

Код	Что означает	Тело
201	Created segment	`Segment`
401	Missing or invalid credentials (code=unauthorized)	`Error`
402	Product access is not active. `code=trial_expired` means the organization's trial ended without payment; `code=subscription_required` means there is no current paid subscription or live trial. In both cases ingest, mutations and plan-gated read/write capabilities are paused until a plan is paid; details.billing_url, when present, points to the cabinet billing page.	`Error`
403	Authenticated but not permitted (code=forbidden)	`Error`
404	Resource not found (code=not_found)	`Error`
422	Invalid v1 rule. Stable details.reason values include segment_not_found, segment_cycle, segment_complexity_limit and unsupported_segment_rule.	`Error`

GET /projects/{id}/segments/{sid}

Get a saved segment

Аутентификация: Bearer: токен доступа (JWT)
operationId: getProjectsIdSegmentsSid

Параметры

Имя	Где	Тип	Описание
`id` обязателен	Путь	`integer (int32)`	Project id.
`sid` обязателен	Путь	`integer (int64)`	Saved segment id.

Ответы

Код	Что означает	Тело
200	Segment	`Segment`
401	Missing or invalid credentials (code=unauthorized)	`Error`
402	Product access is not active. `code=trial_expired` means the organization's trial ended without payment; `code=subscription_required` means there is no current paid subscription or live trial. In both cases ingest, mutations and plan-gated read/write capabilities are paused until a plan is paid; details.billing_url, when present, points to the cabinet billing page.	`Error`
403	Authenticated but not permitted (code=forbidden)	`Error`
404	Resource not found (code=not_found)	`Error`

PATCH /projects/{id}/segments/{sid}

Update a saved segment (analyst+)

Аутентификация: Bearer: токен доступа (JWT)
operationId: patchProjectsIdSegmentsSid

References are live: a successful update affects every future query whose report config contains `segment:{id}`.

Параметры

Имя	Где	Тип	Описание
`id` обязателен	Путь	`integer (int32)`	Project id.
`sid` обязателен	Путь	`integer (int64)`	Saved segment id.

Тело запроса application/json , обязательно

Поле	Тип	Описание
`name` необязательно	`string`
`filters` необязательно	`SegmentDefinition`	Versioned rule. `filters` are ANDed. With `performed` or `not_performed`, predicates apply to the tested event and membership is actor-level. Exact report-derived membership is stored in `source`; actor ids are forbidden. `performed`, `not_performed`, and `source` are mutually exclusive in v1; a source rule requires top-level `filters: []` because its own report filters are captured inside the source branch.

Ответы

Код	Что означает	Тело
200	Updated segment	`Segment`
401	Missing or invalid credentials (code=unauthorized)	`Error`
402	Product access is not active. `code=trial_expired` means the organization's trial ended without payment; `code=subscription_required` means there is no current paid subscription or live trial. In both cases ingest, mutations and plan-gated read/write capabilities are paused until a plan is paid; details.billing_url, when present, points to the cabinet billing page.	`Error`
403	Authenticated but not permitted (code=forbidden)	`Error`
404	Resource not found (code=not_found)	`Error`
422	Request failed validation (code=validation_failed)	`Error`

DELETE /projects/{id}/segments/{sid}

Delete a saved segment (analyst+)

Аутентификация: Bearer: токен доступа (JWT)
operationId: deleteProjectsIdSegmentsSid

Hard delete. Existing report references remain visible but query execution fails with details.reason=segment_not_found.

Параметры

Имя	Где	Тип	Описание
`id` обязателен	Путь	`integer (int32)`	Project id.
`sid` обязателен	Путь	`integer (int64)`	Saved segment id.

Ответы

Код	Что означает	Тело
204	Deleted	пусто
401	Missing or invalid credentials (code=unauthorized)	`Error`
402	Product access is not active. `code=trial_expired` means the organization's trial ended without payment; `code=subscription_required` means there is no current paid subscription or live trial. In both cases ingest, mutations and plan-gated read/write capabilities are paused until a plan is paid; details.billing_url, when present, points to the cabinet billing page.	`Error`
403	Authenticated but not permitted (code=forbidden)	`Error`
404	Resource not found (code=not_found)	`Error`

Источник раздела — docs/api/openapi.yaml репозитория продукта, версия API 1.0.0, OpenAPI 3.0.3, снимок 095579325c2d. Расхождение снимка со спецификацией роняет сборку документации.

← Все разделы API Reference