Analytics building blocks tools

search_expressions: List the expressions defined in a project, or fetch one by ID.
search_aggregates: List the aggregates defined in a project, or fetch one by ID.
search_running_aggregates: List the running (real-time) aggregates 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 Marketing > Customer filters and segments page, since they're often used as named customer groups.

search_expressions

Searches the expressions defined in a project, or fetches one by ID. Expressions are derived attributes computed from a formula: they combine customer or event attributes (properties, aggregates, running aggregates), functions (such as min, max, ifnull, floor, and concat), operators, and string literals.

Omit expression_id to list all expressions. The response gives you the name, context type (customer or event), variable bindings, tags, and which customer or event attributes surface the result. The formula string is not included in list mode. By default the list returns only active (non-archived) expressions; set include_archived to true to return only archived ones. Pass expression_id to fetch the full definition of a single expression, including its formula, ordered variable bindings, exposing properties, filters, and metadata.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`expression_id`	`str`	No	The expression ID. Omit to list all expressions; provide to fetch one.
`include_archived`	`bool`	No	List mode only: if true, return only archived expressions. Defaults to false. Ignored when `expression_id` is provided.

Response parameters

The tool returns an ExpressionsResponse when expression_id is omitted, or an ExpressionResponse when it's provided.

When expression_id is omitted, the ExpressionsResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[ExpressionSummary]`	The expressions defined in the project.
`archived_items_exist`	`bool`	Whether archived expressions exist in this project. Populated only when `include_archived` is false.
`error`	`str \| null`	Error message if the request failed.

The ExpressionSummary object has the following fields:

Field	Type	Description
`id`	`str`	The expression's unique ID.
`name`	`str`	The expression's display name.
`context_type`	`str`	The context the expression operates on: `customer` or `event`.
`event_type`	`str \| null`	The event type, when `context_type` is `event`.
`all_exposing_properties`	`list[ExpressionPropertyRef]`	Customer properties that surface this expression's computed value. Empty if it isn't yet exposed.
`archived`	`bool`	Whether the expression has been archived.
`parametrized`	`bool`	Whether the expression accepts parameters.
`tags`	`list[str]`	User-defined tags.
`created_by_display_name`	`str`	Display name of the creator.
`edited`	`float`	Unix timestamp of the last edit.
`edited_by_display_name`	`str`	Display name of the last editor.
`is_global_object`	`bool`	Whether the expression is shared across projects.
`version_id`	`str`	The version ID of the current definition.
`used_by`	`list[any]`	Segmentations, reports, funnels, or campaigns that reference this expression.

When expression_id is provided, the ExpressionResponse object has the following parameters:

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

The Expression object has the following fields:

Field	Type	Description
`id`	`str`	The expression's unique ID.
`name`	`str`	The expression's display name.
`description`	`str \| null`	An optional written description. Often null.
`formula`	`str`	The formula that combines variables (A–Z) with functions and operators. Available functions: `abs(A)`, `concat(A,B)`, `exp(A)`, `max(A,B)`, `min(A,B)`, `ifnull(A,B)`, `floor(A)`, `ceil(A)`, `lower(A)`, `upper(A)`, `round(A)`, `ln(A)`, `now()`, `length(A)`, `sqrt(A)`, and `power(A,B)`.
`context_type`	`str`	`customer` or `event`.
`event_type`	`str \| null`	The event type, when `context_type` is `event`.
`members`	`list[ExpressionMember]`	Variable bindings in declaration order: the first is A, the second is B, and so on. Each maps to a customer or event attribute, an aggregate, a running aggregate, or an inline constant.
`exposing_properties`	`list[ExpressionPropertyRef]`	Customer properties that surface this expression's computed value.
`filters`	`list[any]`	Filters applied before the expression is evaluated.
`tags`	`list[str]`	User-defined tags.
`archived`	`bool`	Whether the expression has been archived.
`parametrized`	`bool`	Whether the expression accepts parameters.
`parameters`	`any \| null`	The parameter definitions, when `parametrized` is true.
`company_id`	`str`	The project ID this expression belongs to.
`created`	`any`	Unix timestamp of when the expression was created.
`created_by_display_name`	`str`	Display name of the creator.
`edited`	`float`	Unix timestamp of the last edit.
`edited_by_display_name`	`str`	Display name of the last editor.
`is_global_object`	`bool`	Whether the expression is shared across projects.
`version_id`	`str`	The version ID of the current definition.
`used_by`	`list[any]`	Segmentations, reports, funnels, or campaigns that reference this expression.

search_aggregates

Searches the aggregates defined in a project, or fetches one by ID. Aggregates compute a single value over a customer's event history — for example, total purchase count, sum of order values, or date of last session. Aggregate names can be used as variable bindings inside expressions.

Omit aggregate_id to list all aggregates — returns summary records with the name, tags, and archived status. Pass aggregate_id to fetch the full definition of a single aggregate: the event filter, the aggregation type, the date filter, the attribute being aggregated, the group-by, and the output format.

Request parameters

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

Response parameters

The tool returns an AggregatesResponse when aggregate_id is omitted, or an AggregateResponse when it's provided.

When aggregate_id is omitted, the AggregatesResponse object has the following parameters:

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

The AggregateSummary object has the following fields:

Field	Type	Description
`id`	`str`	The aggregate's unique ID.
`name`	`str`	The aggregate's display name.
`archived`	`bool`	Whether the aggregate has been archived.
`tags`	`list[str]`	User-defined tags.
`created`	`float \| null`	Unix timestamp of when the aggregate 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 aggregate 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 aggregate.
`all_exposing_properties`	`list[any]`	Customer or event properties that surface this aggregate's computed value.

When aggregate_id is provided, the AggregateResponse object has the following parameters:

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

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

Field	Type	Description
`type`	`str`	The aggregation type: `count`, `sum`, `avg`, `min`, `max`, `median`, `first`, `last`, or `distinct_count`.
`event`	`any`	The event filter: which events are aggregated, including type, attribute conditions, and date range.
`attribute`	`any \| null`	The event attribute being aggregated. Required for `sum`, `avg`, `min`, `max`, and `median`.
`date_filter`	`any`	The date range applied to events before aggregating.
`independent_if_reused`	`bool`	Whether the aggregate is computed independently when reused across multiple expressions.
`format`	`str`	The output format: `number`, `date`, or `string`.
`group_by`	`any \| null`	The event attribute to group results by. Present only for multi-value aggregations.
`skip`	`int`	The number of values to skip when returning grouped results.
`max_values`	`int`	The maximum number of grouped values to return. 1 for scalar aggregations.
`exposing_properties`	`list[any]`	The direct exposing properties for this aggregate.

search_running_aggregates

Searches the running aggregates in a project, or fetches one by ID. Running aggregates are like aggregates, but they're computed incrementally in real time as events arrive — not on demand. Running aggregate names can be used as variable bindings inside expressions.

Omit running_aggregate_id to list all running aggregates — returns summary records with the name, tags, and archived status. Pass running_aggregate_id to fetch the full definition of a single running aggregate: the event filter, the aggregation type, the date filter, the attribute, and whether the current (in-progress) window is included.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`running_aggregate_id`	`str`	No	The running aggregate ID. Omit to list all running aggregates; provide to fetch one.

Response parameters

The tool returns a RunningAggregatesResponse when running_aggregate_id is omitted, or a RunningAggregateResponse when it's provided.

When running_aggregate_id is omitted, the RunningAggregatesResponse object has the following parameters:

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

The RunningAggregateSummary object has the following fields:

Field	Type	Description
`id`	`str`	The running aggregate's unique ID.
`name`	`str`	The running aggregate's display name.
`archived`	`bool`	Whether the running aggregate has been archived.
`tags`	`list[str]`	User-defined tags.
`created`	`float \| null`	Unix timestamp of when the running aggregate 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 running aggregate 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 running aggregate.
`all_exposing_properties`	`list[any]`	Customer or event properties that surface this running aggregate's computed value.

When running_aggregate_id is provided, the RunningAggregateResponse object has the following parameters:

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

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

Field	Type	Description
`type`	`str`	The aggregation type, restricted to forward types: `count`, `sum`, `avg`, `min`, or `max`.
`event`	`any`	The event filter: which events are aggregated.
`attribute`	`any \| null`	The event attribute being aggregated. Required for `sum`, `avg`, `min`, and `max`.
`date_filter`	`any`	The date range applied to events before aggregating.
`include_current`	`bool`	Whether to include the current (in-progress) aggregation window. When true, the value reflects events received so far in the current period.
`format`	`str`	The output format: `number`, `date`, or `string`.
`group_by`	`any \| null`	The event attribute to group results by.
`max_values`	`int`	The maximum number of grouped values to return.

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 Marketing → Customer filters and segments 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.