list_events

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.

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:

[
  { "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

{
  "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.

Get Started

Connecting Clients

Tools

Resources

Prompts

When to use

Parameters

Custom field filters

Operator vocabulary by field type

Attribution behavior

Example response

Caveats

​When to use

​Parameters

​Custom field filters

​Operator vocabulary by field type

​Attribution behavior

​Example response

​Caveats

When to use

Parameters

Custom field filters

Operator vocabulary by field type

Attribution behavior

Example response

Caveats