Count who an unsaved filter matches
preview_segmentUse this when the founder wants to know how many contacts a filter matches before anything is saved or touched: to check a filter before create_segment, or before tag_contacts/untag_contacts with a segment + limit ("how many would this touch"). It changes nothing. Not for saving the filter (use create_segment) or for listing the people (use search_audience).
rules is a condition tree: {"match": "and"|"or", "conditions": [...]}. Each condition is either a nested group (same shape, up to 5 deep) or a leaf: {"field": "...", "operator": "...", "value": ...} (the attribute field also needs "key"). An empty or omitted tree matches everyone. An unknown field or an operator illegal for its field is refused, not silently skipped, so a bad filter never gets a count that looks real.
Fields and their legal operators, as of this description (the list may grow; list_segments on an existing segment shows a real one if you want to see the shape in practice):
status,trust_tier,deliverability,stage,invite_state,identifier_type,first_source,country,device,browser,os,intent_cluster,unsubscribed_by(contact,owner,complaint; "not" includes people with none recorded),consent(confirmed,signup,imported,owner,v1):eq,neq,in,not_in.valueis a string (eq/neq) or an array of strings (in/not_in).referral_count,quality_score:gt,gte,lt,lte(numericvalue), orbetween(valueis[min, max]).created_at,verified_at,consented_at: the same comparisons, pluswithin_last_days(integervalue) andexists(novalue);verified_atalso takesnot_exists(not verified, asked or not). ISO 8601 dates.submission_count:eq,gt,gte,lt,lte(numericvalue).tag:in/not_in, wherevalueis an array of tag handles (tag_…, fromlist_segments), orexists(has any tag at all, novalue).received_broadcast:in/not_in, wherevalueis an array of 1-50 broadcast handles (bcd_…, must belong to this project) and an optionaldays(integer, 1-3650) means "sent at least that many days ago".inmatches someone who received any of them;not_inmatches someone who received none.is_referrer,is_referred:is_true/is_false, novalue.awaiting_verification:is_true/is_false, novalue. True for someone sent a link to verify their email (an expired one included) who has not clicked it: the Waiting for verification view (withstatussubscribed) and whorecipients: unverifiedon a broadcast reaches. Someone never asked to verify is false.create_segmentrefuses it for a few minutes after the update that added it.utm_source,utm_medium,utm_campaign:eq,neq,in,contains,exists.attribute: a captured custom field. Needs"key"(letters, digits,_,.only) alongsidefield/operator/value. Operators:eq,neq,contains,exists,not_exists,in.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"project": "<project>"
},
"name": "preview_segment"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rules | No | The condition tree — see the tool description for the field/operator grammar. Omit to count everyone. | |
| project | Yes | The project handle, like `prj_…`. |