> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cometly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# list_contacts

> List contacts (profiles) created within a date range, with optional custom-field include and value filtering.

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`](/mcp/tools/get-contact). For ad-performance questions, use [`query_ad_metrics`](/mcp/tools/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:

```json theme={null}
[
  { "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

```json theme={null}
{
  "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`](/mcp/tools/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.