Analytics building blocks tools

list_expressions: List the expressions defined in a project.
get_expression: Get the full definition of an expression, including its formula.
list_aggregates: List the aggregates defined in a project.
get_aggregate: Get the full definition of an aggregate.
list_running_aggregates: List the running (real-time) aggregates in a project.
get_running_aggregate: Get the full definition of a running aggregate.
list_event_segmentations: List the event segmentations in a project.
get_event_segmentation: Get the full definition of an event segmentation.

Event segmentations also appear under the Marketing → Customer filters and segments page, since they're often used as named customer groups.

list_expressions

Lists every expression defined in a project. 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. 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 here — use get_expression for that.

By default the tool returns only active (non-archived) expressions. Set include_archived to true to return only archived ones.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`include_archived`	`bool`	No	If true, return only archived expressions. Defaults to false.

Response parameters

The tool returns an ExpressionsResponse object with 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.

get_expression

Returns the full definition of a single expression. An expression is a derived attribute: a formula that combines up to 26 named variables (A through Z) with functions, operators, and string literals. Each variable maps to a customer or event attribute, an aggregate, a running aggregate, or an inline constant. The result becomes a customer or event attribute usable in segmentations, reports, funnels, and campaigns.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`expression_id`	`str`	Yes	The expression ID returned by `list_expressions`.

Response parameters

The tool returns an ExpressionResponse object with 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.

list_aggregates

Lists every aggregate defined in a project. 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.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.

Response parameters

The tool returns an AggregatesResponse object with 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.

get_aggregate

Returns 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`	Yes	The aggregate ID returned by `list_aggregates`.

Response parameters

The tool returns an AggregateResponse object with 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.

list_running_aggregates

Lists every running aggregate in a project. 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.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.

Response parameters

The tool returns a RunningAggregatesResponse object with 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.

get_running_aggregate

Returns 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`	Yes	The running aggregate ID returned by `list_running_aggregates`.

Response parameters

The tool returns a RunningAggregateResponse object with 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.

list_event_segmentations

Lists every event segmentation defined in a project. Event segmentations partition customers into buckets based on event behavior — for example, which product category was most purchased, or which campaign was last clicked. The response gives you the name, tags, archived flag, and the resources that reference each event segmentation. Segment definitions are not included here — use get_event_segmentation for those.

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

Response parameters

The tool returns an EventSegmentationsResponse object with 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.

get_event_segmentation

Returns 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`	Yes	The event segmentation ID returned by `list_event_segmentations`.

Response parameters

The tool returns an EventSegmentationResponse object with 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.