Customer profiles and event history tools

list_customers: Search for customers in a project.
get_customer_properties: Get all properties on a single customer.
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.

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. The date range is fixed to the last 365 days.

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

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 total number of events matching the filters before pagination.
`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 `list_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': '...'}`.