segments

Preview a Segment predicate

POST /v1/segments/preview

Auth required api.segments.view

Evaluates a candidate SendQL predicate across the org's contacts under run-time query governors and returns the match count plus a small sample, without persisting anything. Use it to validate and size a predicate before saving a Segment. An invalid predicate returns 422 validation_failed with the compile error. This is an evaluation endpoint, not a send endpoint.

Request body

Content type: application/json

source string required

The candidate SendQL predicate to evaluate.

Responses

Errors follow the RFC 7807 problem format — see the error reference.

200 Preview match count + sample application/json

count integer<int64> required

Number of contacts the predicate currently matches.

eval_class string enum required

One of: incremental, sweep, both

sample array<object> required

A bounded sample of matching contacts (id + email).

Each entry in sample:

contact_id string<uuid> required

email string<email> required

401 Missing, malformed, or unknown API key application/problem+json

403 Key lacks the required scope or plan limit violated application/problem+json

422 Query parameter or path value failed validation application/problem+json

429 Per-org rate limit exceeded application/problem+json

500 Unexpected server-side failure. The code is internal_error. The request_id field can be quoted to SendOps support to investigate. application/problem+json