Customer filters and segments tools

search_customer_filters: List the reusable customer filters in a project, or fetch one by ID.
search_segmentations: List the segmentations in a project, or fetch one by ID.
search_autosegments: List the ML-driven autosegments in a project, or fetch one by ID.
search_event_segmentations: List the event segmentations in a project, or fetch one by ID.
create_customer_filter: Create a new saved customer filter in a project.

Event segmentations also appear under the Analytics > Analytics building blocks page, since they compose with expressions, aggregates, and running aggregates.

🚧
Warning
Write tools change your live configuration. Just like changes made in the Marketing dashboard, actions your users or agents take with these tools can have a substantial impact on the audiences your campaigns and analyses target. There is no automatic rollback and activity logging is limited, so review every change and confirm the target before applying it.

search_customer_filters

Searches the customer filters defined in a project, or fetches one by ID. Customer filters are reusable conditions that match customers based on their properties, events, or computed attributes.

Omit customer_filter_id to list all customer filters. The response gives you the name, tags, description, and whether each filter is archived. The boolean formula and the filter conditions themselves are not included in list mode. Pass customer_filter_id to fetch the full definition of a single customer filter, including its boolean formula and the underlying filter conditions. The formula combines zero-based filter indices with & (AND), | (OR), and ! (NOT), for example F0&(F1|!F2).

Detail mode is also how you get a template for a new filter. Fetch a filter whose conditions resemble what you want, then pass its filters and formula to create_customer_filter.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`customer_filter_id`	`str`	No	The customer filter ID. Omit to list all customer filters; provide to fetch one.

Response parameters

The tool returns a CustomerFiltersResponse when customer_filter_id is omitted, or a CustomerFilterResponse when it's provided.

When customer_filter_id is omitted, the CustomerFiltersResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[CustomerFilterSummary]`	The customer filters defined in the project.
`error`	`str \| null`	Error message if the request failed.

The CustomerFilterSummary object has the following fields:

Field	Type	Description
`id`	`str`	The customer filter's unique ID.
`name`	`str`	The customer filter's display name.
`description`	`str \| null`	An optional written description of the filter.
`archived`	`bool`	Whether the filter has been archived.
`tags`	`list[str]`	User-defined tags.
`company_id`	`str`	The project ID this filter belongs to.
`created`	`float \| null`	Unix timestamp of when the filter was created.
`created_by_display_name`	`str`	Display name of the creator.
`edited`	`float \| null`	Unix timestamp of the last edit.
`edited_by_display_name`	`str`	Display name of the last editor.
`version_id`	`str \| null`	The version ID of the current definition.

When customer_filter_id is provided, the CustomerFilterResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`CustomerFilter \| null`	The full customer filter record.
`error`	`str \| null`	Error message if the request failed.

The CustomerFilter object adds the following fields on top of the summary record:

Field	Type	Description
`formula`	`str \| null`	A boolean formula combining filter conditions using `&` (AND), `\|` (OR), and `!` (NOT) over zero-based indices, for example `F0&(F1\|!F2)`.
`filters`	`list[any]`	The filter condition definitions referenced by the formula. Each entry is either a customer attribute condition or a funnel-based condition.

search_segmentations

Searches the segmentations defined in a project, or fetches one by ID. Segmentations partition customers into named buckets (segments) based on customer filter conditions.

Omit segmentation_id to list all segmentations. The response gives you the name, tags, archived flag, and the resources that reference each segmentation. Segment definitions and per-segment metrics are not included in list mode. Pass segmentation_id to fetch the full definition of a single segmentation, including each segment's name and customer filter, the global customer filter, per-segment metrics, map axes configuration, and any BRX integration settings. To list customers belonging to a specific segment, use list_customers_in_segment.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`segmentation_id`	`str`	No	The segmentation ID. Omit to list all segmentations; provide to fetch one.

Response parameters

The tool returns a SegmentationsResponse when segmentation_id is omitted, or a SegmentationResponse when it's provided.

When segmentation_id is omitted, the SegmentationsResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[SegmentationSummary]`	The segmentations defined in the project.
`error`	`str \| null`	Error message if the request failed.

The SegmentationSummary object has the following fields:

Field	Type	Description
`id`	`str`	The segmentation's unique ID.
`name`	`str`	The segmentation's display name.
`archived`	`bool`	Whether the segmentation has been archived.
`tags`	`list[str]`	User-defined tags.
`created`	`any \| null`	Unix timestamp of when the segmentation was created.
`created_by_display_name`	`str`	Display name of the creator.
`edited`	`float \| null`	Unix timestamp of the last edit.
`edited_by_display_name`	`str`	Display name of the last editor.
`is_global_object`	`bool`	Whether the segmentation is shared across projects.
`version_id`	`str \| null`	The version ID of the current definition.
`used_by`	`list[any]`	Campaigns, reports, or other analyses that reference this segmentation.
`parametrized`	`bool`	Whether the segmentation accepts parameters.

When segmentation_id is provided, the SegmentationResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`Segmentation \| null`	The full segmentation record.
`error`	`str \| null`	Error message if the request failed.

The Segmentation object adds the following fields on top of the summary record:

Field	Type	Description
`customer_filter`	`any \| null`	The global customer filter applied before segments are evaluated. Customers who do not match are left out of every segment.
`segments`	`list[any]`	The segment definitions. Each segment has an `_id`, a `name`, and a `customer_filter` that decides which customers go in that bucket.
`metrics`	`list[any]`	Metrics computed for each segment, for example total revenue or purchase count. Each entry has a `context_format` field.
`segmentation_map_axes`	`any \| null`	Map visualization axes: the x, y, and size metric indices.
`customer_count_format`	`str`	How per-segment customer counts are formatted: `value`, `percentage`, or `average`.
`independent_if_reused`	`bool`	Whether the segmentation is computed independently when reused across multiple analyses.
`content_integration`	`any \| null`	BRX content integration settings.
`discovery_integration`	`any \| null`	BRX discovery integration settings.
`merchandising_integration`	`any \| null`	BRX merchandising integration settings.

search_autosegments

Searches the autosegments defined in a project, or fetches one by ID. Autosegments use machine learning to discover meaningful customer groups automatically from behavioral and property metrics — no manual segment conditions required.

Omit autosegment_id to list all autosegments. The response gives you the name, tags, initiative, and the current job status (draft, running, successful, or failed) with the last run timestamp. The metric list and detailed job info (progress, stage, error) are not included in list mode. Pass autosegment_id to fetch the full definition of a single autosegment, including the metrics that drive segment discovery, the global customer filter, the minimum segment size, and the full job execution info (status, progress, stage, error). Note: the generated segment data itself (results) is not available through this endpoint.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`autosegment_id`	`str`	No	The autosegment ID. Omit to list all autosegments; provide to fetch one.

Response parameters

The tool returns an AutosegmentsResponse when autosegment_id is omitted, or an AutosegmentResponse when it's provided.

When autosegment_id is omitted, the AutosegmentsResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[AutosegmentSummary]`	The autosegments defined in the project.
`error`	`str \| null`	Error message if the request failed.

The AutosegmentSummary object has the following fields:

Field	Type	Description
`id`	`str`	The autosegment's unique ID.
`name`	`str`	The autosegment's display name.
`created`	`any \| null`	Unix timestamp of when the autosegment was created.
`created_by_display_name`	`str`	Display name of the creator.
`edited`	`float \| null`	Unix timestamp of the last edit.
`edited_by_display_name`	`str`	Display name of the last editor.
`tags`	`list[str]`	User-defined tags.
`initiative_id`	`str \| null`	The initiative this autosegment belongs to, if any.
`is_global_object`	`bool`	Whether the autosegment is shared across projects.
`job_info`	`AutosegmentJobInfoSummary \| null`	Current execution status: the `status` (`draft`, `running`, `successful`, or `failed`) and `last_run_at` timestamp.

When autosegment_id is provided, the AutosegmentResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`Autosegment \| null`	The full autosegment record.
`error`	`str \| null`	Error message if the request failed.

The Autosegment object adds the following fields on top of the summary record:

Field	Type	Description
`company_id`	`str`	The project ID this autosegment belongs to.
`description`	`str \| null`	An optional written description.
`archived`	`bool`	Whether the autosegment has been archived.
`version_id`	`str \| null`	The version ID of the current definition.
`used_by`	`list[any]`	Campaigns, reports, or other analyses that reference this autosegment.
`all_exposing_properties`	`list[any]`	Customer properties that surface this autosegment's output values.
`definition`	`AutosegmentDefinition \| null`	The full configuration: `metrics`, `customer_filter`, `min_customers_per_segment` (default 5000), `min_customers_per_segment_is_relative`, and `customer_attributes`.
`job_info`	`AutosegmentJobInfo \| null`	The full job info: `status`, `last_run_at`, `queued_at`, `stage`, `progress` (a value between 0.0 and 1.0), `error`, and `submitted_job_id`.

search_event_segmentations

Searches the event segmentations defined in a project, or fetches one by ID. Event segmentations partition customers into buckets based on event behavior, for example which product category was most purchased or which campaign was last clicked.

Omit event_segmentation_id to list all event segmentations. The response gives you the name, tags, archived flag, and the resources that reference each event segmentation. Segment definitions are not included in list mode. Pass event_segmentation_id to fetch the full definition of a single event segmentation, including each segment's name and event attribute filter.

Event segmentations also appear under the Analytics → Analytics building blocks page.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`event_segmentation_id`	`str`	No	The event segmentation ID. Omit to list all event segmentations; provide to fetch one.

Response parameters

The tool returns an EventSegmentationsResponse when event_segmentation_id is omitted, or an EventSegmentationResponse when it's provided.

When event_segmentation_id is omitted, the EventSegmentationsResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[EventSegmentationSummary]`	The event segmentations defined in the project.
`error`	`str \| null`	Error message if the request failed.

The EventSegmentationSummary object has the following fields:

Field	Type	Description
`id`	`str`	The event segmentation's unique ID.
`name`	`str`	The event segmentation's display name.
`event_type`	`str \| null`	The event type the segmentation partitions customers by.
`archived`	`bool`	Whether the event segmentation has been archived.
`tags`	`list[str]`	User-defined tags.
`created`	`float \| null`	Unix timestamp of when the event segmentation was created.
`created_by_display_name`	`str`	Display name of the creator.
`edited`	`float \| null`	Unix timestamp of the last edit.
`edited_by_display_name`	`str`	Display name of the last editor.
`is_global_object`	`bool`	Whether the event segmentation is shared across projects.
`version_id`	`str \| null`	The version ID of the current definition.
`used_by`	`list[any]`	Segmentations, reports, funnels, or campaigns that reference this event segmentation.
`all_exposing_properties`	`list[any]`	Properties that surface this event segmentation's computed value.

When event_segmentation_id is provided, the EventSegmentationResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`EventSegmentation \| null`	The full event segmentation record.
`error`	`str \| null`	Error message if the request failed.

The EventSegmentation object adds the following fields on top of the summary record:

Field	Type	Description
`segments`	`list[any]`	The segment definitions. Each segment has a `name` (the bucket label) and a `filter` (the event attribute conditions).
`exposing_properties`	`list[any]`	The direct exposing properties for this event segmentation.

create_customer_filter

Creates a new saved customer filter in a project. A customer filter is a reusable set of conditions that matches customers by their properties, events, or computed attributes, and other objects reference it by ID. Reach for this tool when an agent needs a durable audience definition rather than a one-off query, for example a "lapsed high-value buyers" filter that a segmentation or a report can then reuse.

Build the audience from two parts. filters is a zero-based list of condition atoms, and formula combines their indices with & (AND), | (OR), and ! (NOT), for example (F0|F1)&!F2. Every index named in the formula must exist in filters, or the call fails with Boolean expression filter F99 was not declared. Omit both to match all customers.

Each atom is either a customer attribute condition, {"type": "attribute", "attribute": {...}, "constraint": {...}}, or a funnel-based condition, {"type": "funnel_steps", "steps": [...]}. The shapes are strict, and several near-misses pass validation upstream and then match the wrong customers, so the reliable approach is to fetch a similar existing filter with search_customer_filters(customer_filter_id=...) and adapt its filters and formula. Four mistakes account for most failures: attribute.type is property, never customer_property; string operands are {"type": "constant", "value": ...}, never a bare {"value": ...}; a boolean value is the string "true" or "false", not a JSON boolean; and relative date constraints take amount, units, and tense instead of operands.

🚧
Warning
Creating a filter doesn't attach it to anything. To target an email campaign at this audience, fetch the new filter with search_customer_filters(customer_filter_id=...) and copy its filters and formula inline into the campaign payload. The Marketing API doesn't resolve a saved filter by ID during campaign creation — it drops the unknown field without complaint, and the campaign ends up targeting every customer.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`name`	`str`	Yes	The display name for the new customer filter.
`filters`	`list`	No	The filter condition atoms, zero-based. Omit or pass an empty list to match all customers.
`formula`	`str`	No	A boolean expression over the filter indices, for example `F0&F1`. Omit to match all customers.
`tags`	`list`	No	Tags for organizing customer filters.

Response parameters

The tool returns a WriteResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the write succeeded.
`id`	`str \| null`	The ID of the newly created customer filter.
`error`	`str \| null`	The upstream error or validation detail if the write failed.