---
title: "Preview a segment filter"
method: POST
path: "/api/v1/segments/preview"
tags: ["Segments"]
---

# Preview a segment filter

`POST /api/v1/segments/preview`

Count how many people currently match a filter, without saving. Use it to check the audience before saving a segment.

## Request body

- object
  - `filterExpression` object, required — The audience filter: a tree of predicates over person attributes, related data, and events. Discover valid `attr` tokens and operators with segments_catalog (GET /api/v1/segments/catalog).
    - `kind` 'person', required
    - `op` 'AND' | 'OR', required
    - `predicates` union[], required
      - union
        - object
          - `kind` 'has_relationship', required
          - `connector` 'AND' | 'OR'
          - `customObjectType` string, required
          - `attributeFilters` object[], required
            - `attr` string, required
            - `path` string[]
            - `type` 'STRING' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'JSON' | 'ARRAY', required
            - `op` 'eq' | 'neq' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'gt' | 'gte' | 'lt' | 'lte' | 'on' | 'before' | 'after' | 'between' | 'in_last_n' | 'in_next_n' | 'more_than_n_ago' | 'more_than_n_from_now' | 'exactly_n_from_today' | 'is_null' | 'is_not_null', required
            - `value` union
              - …
          - `path` object[]
            - `customObjectType` string, required
            - `direction` 'parent_to_child' | 'child_to_parent'
            - `relationshipType` string
            - `attributeFilters` object[], required
              - …
        - object
          - `kind` 'person_attribute', required
          - `connector` 'AND' | 'OR'
          - `attr` string, required
          - `path` string[]
          - `type` 'STRING' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'JSON' | 'ARRAY', required
          - `op` 'eq' | 'neq' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'gt' | 'gte' | 'lt' | 'lte' | 'on' | 'before' | 'after' | 'between' | 'in_last_n' | 'in_next_n' | 'more_than_n_ago' | 'more_than_n_from_now' | 'exactly_n_from_today' | 'is_null' | 'is_not_null', required
          - `value` union
            - string
            - number
            - boolean
            - union[]
              - …
            - object
              - …
            - object
              - …
            - object
              - …
        - object
          - `kind` 'person_group', required
          - `connector` 'AND' | 'OR'
          - `filters` object[], required
            - `attr` string, required
            - `path` string[]
            - `type` 'STRING' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'JSON' | 'ARRAY', required
            - `op` 'eq' | 'neq' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'gt' | 'gte' | 'lt' | 'lte' | 'on' | 'before' | 'after' | 'between' | 'in_last_n' | 'in_next_n' | 'more_than_n_ago' | 'more_than_n_from_now' | 'exactly_n_from_today' | 'is_null' | 'is_not_null', required
            - `value` union
              - …
        - object
          - `kind` 'event', required
          - `connector` 'AND' | 'OR'
          - `eventName` string, required
          - `occurred` boolean, required
          - `propertyFilters` object[]
            - `key` string, required
            - `path` string[]
            - `type` 'STRING' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'JSON' | 'ARRAY', required
            - `op` 'eq' | 'neq' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'gt' | 'gte' | 'lt' | 'lte' | 'on' | 'before' | 'after' | 'between' | 'in_last_n' | 'in_next_n' | 'more_than_n_ago' | 'more_than_n_from_now' | 'exactly_n_from_today' | 'is_null' | 'is_not_null', required
            - `value` union
              - …
          - `window` object
            - `op` 'in_last_n' | 'more_than_n_ago' | 'between' | 'before' | 'after' | 'on', required
            - `value` union
              - …

## Response `200`

Success

- object
  - `count` integer, required — People currently matching the filter (capped when huge).

## Other responses

- `400` — Validation failed or the request cannot proceed.
- `401` — Missing, malformed, or revoked API key.
- `404` — The resource does not exist in this organization.
- `409` — Conflicts with the current state (duplicates, wrong lifecycle state).
- `422` — The request is well-formed but semantically invalid.
- `429` — Rate limit exceeded — retry after `Retry-After`.
- `500` — Internal server error.
- `503` — Transient error — retry with a narrower request.

---

[API](https://skmtc.net/useboom/apis/boom-api.md) · [All operations](https://skmtc.net/useboom/apis/boom-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/useboom/boom-api/revisions/00f873e07076/schema)