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.

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

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).

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.