A valid request URL is required to generate request examples{
"count": 412,
"sample": [
{
"id": "0f1c…",
"name": "Ana",
"email": "ana@acme.com",
"created_at": "2026-08-01T12:00:00Z"
}
]
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Preview a segment's audience
Requires customers:read. How many contacts match as of now, and a page of them — the two questions somebody asks before saving an audience.
Computed from the definition rather than read from the materialized membership, which is what makes it different from the members count on the segment itself. Send a definition in the body to preview an edit that has not been stored; omit it and the stored one is used. Either way it is validated by the gate the write uses.
A POST because the definition rides in the body. It writes nothing.
A valid request URL is required to generate request examples{
"count": 412,
"sample": [
{
"id": "0f1c…",
"name": "Ana",
"email": "ana@acme.com",
"created_at": "2026-08-01T12:00:00Z"
}
]
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Autorizações
A staff session token, uk_st_…. Minted by sign-up, sign-in or the two-factor exchange. Only a 401 means it is spent; not_a_member (403) is about the organization named in X-Organization-Id and leaves the token good for the others.
Cabeçalhos
The organization the caller is acting on — the org_… code that appears in the panel URL. It identifies; the membership JOIN is what authorizes, so a forged code reads nothing: the answer is not_a_member (403), which does not mean the session is over. Absent, the session's default organization answers, or — if that membership was revoked while the session was open — any other one the caller still holds.
Parâmetros de caminho
Corpo
A conjunction of groups; within a group, a disjunction of conditions — (A OR B) AND C. Two levels and no more: arbitrary nesting is a precedence question and a form nobody can draw.
What it refuses. A condition this engine cannot state exactly is refused rather than approximated, and two of those refusals are decisions rather than gaps. A custom contact attribute (attributes.tier) has no store behind it — the contact columns are the profile and the first-touch attribution — so matching one would mean matching something else. An entitlement is resolved by the entitlements engine, with overrides that replace rather than maximise, an expiry, a dunning grace, and a status that can honestly answer "cannot tell"; a segment targets the plan instead, which is a row. An activity metric in a test environment is refused too: the meter never records test, so the condition could only ever match nobody.
Show child attributes
Show child attributes
{
"groups": [
{
"conditions": [
{
"source": "attribute",
"field": "email_verified",
"operator": "is_true"
}
]
},
{
"conditions": [
{
"source": "event",
"operator": "not_occurred",
"value": "checkout.paid",
"days": 30
}
]
}
]
}