Create Segment

A reusable workspace-scoped audience filter composed of one or more criteria joined by a single conjunction.

Public API requests are validated against a safe-condition whitelist; criteria outside the whitelist return 422 with a pointer to the developer community.

The records the filter matches, returned inline so selecting a set and reading it is one call instead of a filter plus a paginated crawl.

Column-oriented. fields states the column order once and rows carries bare value arrays. Repeating every key on every record roughly doubles the payload for a projection of a few scalars, which defeats the purpose of asking for a projection. Zip fields with each row to reconstruct objects.

truncated tells you whether rows is the whole set. A total count is present only when the request opts in with results.count: true, because counting a truncated set requires a second evaluation of the filter. Use the workspace stats endpoint when you need only a number.

Saved contact and order filters support results. Other filter classes return 422 until the API defines an explicit projection allow-list for them.

You set the budget; the response tells you what it cost. How much a client can absorb is not something this API can know, so results.max_bytes and results.limit are yours to set and their defaults (3 KB of rows, 500 rows) are only a conservative starting point. Every response reports estimated bytes, bytes_per_record and the max_bytes actually applied, so one call is enough to size every call after it. These estimates are measured before final response encoding, which can be slightly larger for values such as timestamps; leave headroom. When a response is truncated, suggested_max_bytes is the value to retry with to get the whole set in one call (extrapolated from the widest row RETURNED SO FAR, so it can still undershoot if later records are wider - check truncated again on the retry), and guidance spells out the alternatives. The only ceiling you cannot raise is the server's own (4 MB of rows per response), which protects the server rather than your context; past it, page with next_after or narrow the filter.

max_bytes bounds the ROWS, not the whole response. Over MCP the payload is carried twice (structured plus text mirror) alongside the filter definition, which measured at 2.0x-2.9x the rows on the wire. So when sizing against a client tool-result cap, divide by ~3. The default is already sized that way. suggested_max_bytes comes back in the same rows units, so it can be passed straight back.