> ## 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_events

> List individual conversion events with optional attribution, field selection, and custom-field-value filtering.

Returns one row per conversion event in a date range. Use this when the user wants to see *individual* events. For aggregated questions (totals, ROAS, trends), prefer [`query_ad_metrics`](/mcp/tools/query-ad-metrics).

## When to use

* *"Show me yesterday's purchases."*
* *"List sign-ups from Google Ads last week."*
* *"What were the most recent leads attributed to Facebook?"*
* *"List purchases from contacts where Customer Plan is Premium this month."*

## Parameters

| Parameter              | Type      | Required    | Description                                                                                                                                                                                                              |
| ---------------------- | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `start_date`           | string    | Yes         | `YYYY-MM-DD HH:MM:SS`, interpreted in your Space's timezone.                                                                                                                                                             |
| `end_date`             | string    | Yes         | `YYYY-MM-DD HH:MM:SS`, must be after `start_date`.                                                                                                                                                                       |
| `query_mode`           | string    | No          | `profile` (default) or `company`.                                                                                                                                                                                        |
| `event_names`          | string\[] | No          | Filter by event names. The model passes user-facing custom event labels here ("Demo Submission") and the server translates to the internal slug (`custom_event_9`).                                                      |
| `sources`              | string\[] | No          | Filter by traffic sources. When set, `attribution_model` and `attribution_window` are required.                                                                                                                          |
| `attribution_model`    | string    | Conditional | Required when `sources` is set.                                                                                                                                                                                          |
| `attribution_window`   | integer   | Conditional | Required when `sources` is set. `0` = LTV.                                                                                                                                                                               |
| `fields`               | string\[] | No          | Which fields to return per event. Default: `["id", "event_time_utc"]`. Touchpoint fields (`ad_id`, `ad_name`, `adset_id`, `adset_name`, `campaign_id`, `campaign_name`, `account_id`, `account_name`) require `sources`. |
| `per_page`             | integer   | No          | 1–4000. Default 200.                                                                                                                                                                                                     |
| `cursor`               | string    | No          | Pagination cursor from a prior response's `next_cursor`.                                                                                                                                                                 |
| `custom_field_filters` | array     | No          | AND-joined conditions on the owning contact's custom profile fields. See **Custom field filters** below.                                                                                                                 |

## Custom field filters

`custom_field_filters` is a flat array of conditions, ANDed together. Each condition references a custom profile field 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 ask about "Customer Plan" or "Customer Age." Slots that haven't been configured with a label are rejected with a `validation_error`.

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

## Attribution behavior

Without `sources`, you get one row per event in the date range — no attribution.

With `sources`, multi-touch attribution applies and **each event may return multiple rows** — one per attributed touchpoint. A $100 conversion attributed across 4 touchpoints via `linear` returns 4 rows, each crediting $25. Single-touch models (`first_touch`, `last_touch`) return one row per event.

## Example response

```json theme={null}
{
  "data": [
    {
      "id": "8123",
      "event_time_utc": "2026-05-13T14:22:10Z",
      "event_name": "purchase",
      "amount": 89.50,
      "ad_name": "Spring Sale — Carousel A",
      "campaign_name": "Spring 2026 — Acquisition",
      "source": "facebook_ads"
    }
  ],
  "next_cursor": "eyJpZCI6ODEyMywiZXZlbnRfdGltZV91dGMiOiIyMDI2LTA1LTEzVDE0OjIyOjEwWiJ9",
  "prev_cursor": null,
  "per_page": 200
}
```

## Caveats

* **Default fields** are minimal (`id`, `event_time_utc`) to keep responses fast. Ask for more via `fields` when you actually need them.
* **Touchpoint fields require sources.** Asking for `ad_name` without setting `sources` returns a validation error.
* **`event_url`** is computed from `metadata.host + path + query` — useful for "what page did this fire from?" questions.
* **`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.