Customer profiles and event history tools

list_customers: Search for customers in a project.
get_customer_properties: Get all properties on a single customer.
get_customer_attribute_values: Compute aggregate or expression values for a single customer in real time.
list_customer_events: List events for a single customer.
list_customers_in_segment: List the customers in a named segment.

list_customers

Searches for customers in a project and returns matching records. Each result has an internal ID and a dictionary of identifier values keyed by field name, for example {'registered': '[email protected]', 'cookie': '...'}. The query parameter searches across identifier values such as email address or cookie ID. It does not search property values.

Pagination is controlled with skip and count; together they must not exceed 1,000. Identifier values marked as private are masked to '******' when the session does not have the administration.pii.flag permission. The masking is enforced on the server and cannot be overridden from the tool.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`query`	`str`	No	Text to search across customer identifier values. Defaults to an empty string.
`skip`	`int`	No	Pagination offset. Defaults to 0. `skip` plus `count` must not exceed 1,000.
`count`	`int`	No	Number of results to return. Defaults to 20. Maximum 1,000.

Response parameters

The tool returns a CustomersResponse object with the following parameters:

Parameter	Type	Description
`data`	`list[Customer]`	The matching customer records.
`evaluation_stats`	`any \| null`	Query evaluation statistics, when available.
`limit`	`int`	The maximum number of results requested.
`matched`	`int`	The number of customers matched by the filter.
`matched_exactly`	`int`	The number matched exactly, not fuzzy.
`matched_limited`	`bool`	Whether the match count was capped by a server limit. The true total may be higher.
`skip`	`int`	The pagination offset that was applied.
`total`	`int`	The total number of customers in the project.

The Customer object has the following fields:

Field	Type	Description
`id`	`str`	The internal customer ID. Use this as `customer_id` in other tools.
`ids`	`dict[str, any \| null]`	Identifier values keyed by field name, for example `{'registered': '[email protected]', 'cookie': '...'}`.

get_customer_properties

Returns every property currently set on a single customer, along with each property's last update timestamp. The response also includes the customer's expression-derived computed attributes. Property values marked as private are masked to '******' when the session does not have the administration.pii.flag permission.

Request parameters

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

Response parameters

The tool returns a CustomerPropertiesResponse object with the following parameters:

Parameter	Type	Description
`id`	`str`	The internal customer ID.
`company_id`	`str`	The project ID this customer belongs to.
`created`	`int`	Unix timestamp of when the customer record was created.
`ids`	`dict[str, str \| null]`	Identifier values keyed by field name.
`properties`	`dict[str, CustomerProperty]`	Property values keyed by name. Each entry has a `value` and a `last_update`.
`attributes`	`list[any]`	Expression-derived computed attribute values for this customer.
`failed_attributes`	`list[any]`	Expressions that failed to evaluate for this customer.
`export_archived_events`	`bool`	Whether archived events are included when this customer is exported.

get_customer_attribute_values

Computes one or more aggregate or expression values for a single customer, live from that customer's raw event history. This is the tool to reach for when you need to know what an attribute actually evaluates to for one person, for example when working out why a customer does or doesn't land in a segmentation.

It fills a real gap left by get_customer_properties. Many aggregates, most_common types in particular, have no exposing properties, so their computed value is never written back to the customer profile and never shows up in the property list. Values here are computed at call time and aren't cached, so they change as new events arrive.

Pass each attribute as a {"type": ..., "id": ...} descriptor, where type is aggregate or expression and id comes from search_aggregates or search_expressions. When some attributes can't be evaluated, the response sets partial to true and lists their IDs in failed_attributes. Values that did compute are still returned, so a partial result is still useful.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`customer_id`	`str`	Yes	The internal customer ID returned by `list_customers`. It must be the internal ID, not an external identifier such as an email address or cookie ID.
`attributes`	`list[dict]`	Yes	The attributes to evaluate. Each entry needs a `type` of `aggregate` or `expression` and an `id` from `search_aggregates` or `search_expressions`.

Response parameters

The tool returns a CustomerAttributeValuesResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`attributes`	`list[CustomerAttributeValue]`	The computed values, in the same order as the `attributes` you passed in.
`failed_attributes`	`list[str]`	IDs of the attributes that couldn't be evaluated, for example because no events matched.
`partial`	`bool`	`true` when at least one attribute failed to evaluate. Successful values are still returned.
`error`	`str \| null`	Error message if the whole request failed.

The CustomerAttributeValue object has the following fields:

Field	Type	Description
`name`	`str`	The attribute's display name, for example `Total purchases`.
`id`	`str \| null`	The ID of the aggregate or expression that produced the value. A `null` value means it couldn't be matched.
`value`	`any`	The computed value: a number, string, boolean, or list. It's `null` when the attribute couldn't be evaluated.

list_customer_events

Lists events for a single customer, with an optional filter by event type. Events are returned in reverse chronological order by default. Each event has a type (such as purchase or session_start), a Unix timestamp, and a properties dictionary with event-specific data.

Use days_back to set the history window. It defaults to the last 365 days and accepts up to 3,650 days, and events older than the window are excluded. The window counts relative calendar days in your own Marketing user timezone, and day boundaries align to that timezone. There's no separate timezone parameter to set.

Event property values marked as private are masked to '******' when the session does not have the administration.pii.flag permission.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`customer_id`	`str`	Yes	The internal customer ID returned by `list_customers`.
`event_types`	`list[str] \| null`	No	Event types to include, for example `['purchase', 'page_visit']`. Omit to return all event types.
`skip`	`int`	No	Pagination offset. Defaults to 0.
`limit`	`int`	No	Number of events to return. Defaults to 50. Maximum 500.
`order_direction`	`str`	No	`desc` (most recent first, default) or `asc` (oldest first).
`days_back`	`int`	No	Days of event history to include. Defaults to 365. Maximum 3,650.

Response parameters

The tool returns a CustomerEventsResponse object with the following parameters:

Parameter	Type	Description
`data`	`list[CustomerEvent]`	The events that matched the filters.
`total`	`int`	The number of events the customer has in the `days_back` window, counted before pagination and regardless of `event_types`.
`matched`	`int \| null`	The number of events in the window that match `event_types`. Use this, not `total`, to decide whether to paginate.
`limit`	`int`	The maximum number of events requested.
`skip`	`int`	The pagination offset that was applied.

The CustomerEvent object has the following fields:

Field	Type	Description
`type`	`str`	The event type identifier, for example `purchase` or `page_visit`.
`timestamp`	`float`	Unix timestamp of when the event occurred.
`properties`	`dict[str, any]`	Event property values keyed by property name.

list_customers_in_segment

Lists customers who belong to a specific named segment inside a segmentation. The segment name must match exactly. If the name is not found, the tool returns an error that lists the segment names that do exist.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`segmentation_id`	`str`	Yes	The segmentation ID returned by `search_segmentations`.
`segment_name`	`str`	Yes	The exact name of the segment to filter by, for example `At-Risk`.
`skip`	`int`	No	Pagination offset. Defaults to 0. `skip` plus `count` must not exceed 1,000.
`count`	`int`	No	Number of results to return. Defaults to 20. Maximum 1,000.

Response parameters

The tool returns a CustomersResponse object with the following parameters:

Parameter	Type	Description
`data`	`list[Customer]`	The matching customer records.
`evaluation_stats`	`any \| null`	Query evaluation statistics, when available.
`limit`	`int`	The maximum number of results requested.
`matched`	`int`	The number of customers matched by the segment filter.
`matched_exactly`	`int`	The number matched exactly, not fuzzy.
`matched_limited`	`bool`	Whether the match count was capped by a server limit. The true total may be higher.
`skip`	`int`	The pagination offset that was applied.
`total`	`int`	The total number of customers in the project.

The Customer object has the following fields:

Field	Type	Description
`id`	`str`	The internal customer ID.
`ids`	`dict[str, any \| null]`	Identifier values keyed by field name, for example `{'registered': '[email protected]', 'cookie': '...'}`.