segments

Force a Segment re-evaluation

POST /v1/segments/{id}/evaluate

Auth required api.segments.manage

Forces the full membership re-evaluation the periodic sweep would eventually do, for a caller that has just changed data the predicate reads and does not want to wait. On writes, {id} resolves as a UUID or, failing that, as the Segment's org-unique key.

Always 202: the recompute is an unbounded pass over the whole contact population, so it is queued rather than held open on the request, and the refreshed count arrives on the next GET /v1/segments/{id}. Saves are different — POST /v1/segments and PUT /v1/segments/{id} evaluate inline and return the count themselves, so this route is for the case where the definition did not change.

Only active Segments are evaluable; a paused, invalid or archived one is 409 conflict rather than a 202 for work that would never run. A short per-Segment cooldown (shared with the dashboard's re-evaluate action) returns 429 when called again too soon.

Path parameters

id string required

The Segment's UUID or, when the value does not parse as a UUID, its org-unique key. Unknown handles read as 404 not_found. Accepted on every Segment route, read and write alike.

Responses

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

202 The re-evaluation was queued application/json

segment_id string<uuid> required

status string enum required

One of: queued

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

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

404 Resource not found application/problem+json

409 The mutation is rejected by a state rule rather than a bad request. The code is conflict. 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