list_contacts

Returns one row per contact (profile) created in the date range, or matching an exact email address, with primary email, name, phone, and location. Optionally enriched with all known emails, Cometly tracking tokens, or the full set of custom profile fields.

When to use

“Who signed up last week?”
“List leads from this month.”
“Show me new contacts created today.”
“Find contacts where Customer Plan is Premium.”
“Do we have a contact for jane@acme.com?” → pass email, no date range needed.

For a single contact’s full journey, use get_contact. For ad-performance questions, use query_ad_metrics. Searching for a specific named person by name should go through search_workspace first — but an exact email address is better served by this tool’s email parameter.

Parameters

Parameter	Type	Required	Description
`start_date`	string	Conditional	`YYYY-MM-DD HH:MM:SS`, interpreted in your Space’s timezone. Filters by contact creation date. Required unless `email` is supplied, and must be sent as a pair with `end_date`.
`end_date`	string	Conditional	`YYYY-MM-DD HH:MM:SS`, must be after `start_date`. Required unless `email` is supplied, and must be sent as a pair with `start_date`.
`email`	string[]	No	Look contacts up by exact email address instead of (or alongside) the date range. Matching is exact and case-insensitive. Matches both the contact’s primary address and any of its alternate addresses, including addresses captured on profiles later merged into the contact. Up to 100 addresses per call. A contact matched on an alternate address comes back with its primary in `email`, not the address you queried — set `include_all_emails` when passing more than one address, or you cannot tell which input produced which row.
`per_page`	integer	No	1–5000. Default 200.
`cursor`	string	No	Pagination cursor from a prior response’s `next_cursor`.
`include_all_emails`	boolean	No	Adds an array of all known email addresses per contact (including merged profiles).
`include_comet_tokens`	boolean	No	Adds the contact’s last 5 Cometly tracking tokens.
`include_custom_fields`	boolean	No	Includes the 30 custom profile fields (`profile_field_1` through `profile_field_30`).
`use_custom_field_labels`	boolean	No	When `include_custom_fields` is true, replaces raw column names with user-defined labels (e.g. `"Customer Age"`). Always set this to true unless the user explicitly wants raw column names.
`custom_field_filters`	array	No	AND-joined conditions on custom profile fields. See below.

Custom field filters

Flat array of AND-joined conditions referencing slots configured on your Space:

[
  { "field": "profile_field_5",  "operator": "equal_to",     "value": "Premium" },
  { "field": "profile_field_18", "operator": "greater_than", "value": 30 },
  { "field": "profile_field_27", "operator": "between",      "start": "2025-01-01", "end": "2025-12-31" }
]

The tool’s input schema lists the labels and types your Space has configured for slots 1–30, so the model picks the right slug automatically when you mention a user-facing label like “Customer Plan” or “Customer Age.” Slots that haven’t been configured are rejected with validation_error. Maximum 10 conditions per request.

Operator vocabulary by field type

Slot range	Type	Operators
`profile_field_1` – `profile_field_15`	text	`equal_to`, `not_equal_to`, `contains`, `not_contains`, `starts_with`, `ends_with`, `contains_word`, `any`, `unknown`
`profile_field_16` – `profile_field_25`	number	`equal_to`, `not_equal_to`, `greater_than`, `greater_than_or_equal_to`, `less_than`, `less_than_or_equal_to`, `any`, `unknown`
`profile_field_26` – `profile_field_30`	date	`equal_to`, `between`, `greater_than`, `less_than`, `age_greater_than`, `age_equal_to`, `age_less_than`, `any`, `unknown`

any matches contacts where the field has a value; unknown matches contacts where the field is empty or unset. For numeric fields, any requires a value greater than 0 and unknown matches 0 or unset. Date comparisons (equal_to, greater_than, less_than, between) use your space’s configured timezone; equal_to matches the full calendar day.

Example response

{
  "data": [
    {
      "id": 41902,
      "email": "jane@example.com",
      "name": "Jane Doe",
      "phone": null,
      "location": "Austin, TX, US",
      "Customer Plan": "Premium",
      "Customer Age": 34
    }
  ],
  "next_cursor": "eyJpZCI6NDE5MDJ9",
  "prev_cursor": null,
  "per_page": 200
}

When use_custom_field_labels is true, the response keys carry the labels you configured ("Customer Plan", "Customer Age"); otherwise they appear as raw profile_field_N keys.

Caveats

Primary data only. The list endpoint returns one email, name, phone, and location per contact. For all known values across merged profiles, use get_contact or pass include_all_emails: true.
Order is newest first by id descending. Cursor pagination uses id as the cursor key.
Empty filter slots are rejected. Filtering on profile_field_19 when slot 19 has no label returns a validation error rather than silently returning zero rows.
not_equal_to / not_contains exclude unset values. Contacts where the field is unset are not included. Add a separate unknown condition if you need to capture those.
email is an array only. Unlike the HTTP endpoint’s query string, the MCP tool’s input schema doesn’t accept a comma-separated string for email — always pass an array of addresses, even for a single lookup.
No match is not an error. An email (or date range) with no matching contacts returns an empty data array, not a validation error.

Get Started

Connecting Clients

Tools

Resources

Prompts

When to use

Parameters

Custom field filters

Operator vocabulary by field type

Example response

Caveats

​When to use

​Parameters

​Custom field filters

​Operator vocabulary by field type

​Example response

​Caveats

When to use

Parameters

Custom field filters

Operator vocabulary by field type

Example response

Caveats