list_contacts

Returns one row per contact (profile) created in the date range, 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.”

For a single contact’s full journey, use get_contact. For ad-performance questions, use query_ad_metrics.

Parameters

Parameter	Type	Required	Description
`start_date`	string	Yes	`YYYY-MM-DD HH:MM:SS`, interpreted in your Space’s timezone. Filters by contact creation date.
`end_date`	string	Yes	`YYYY-MM-DD HH:MM:SS`, must be after `start_date`.
`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.

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