Skip to main content

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.

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

ParameterTypeRequiredDescription
start_datestringYesYYYY-MM-DD HH:MM:SS, interpreted in your Space’s timezone.
end_datestringYesYYYY-MM-DD HH:MM:SS, must be after start_date.
query_modestringNoprofile (default) or company.
event_namesstring[]NoFilter 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).
sourcesstring[]NoFilter by traffic sources. When set, attribution_model and attribution_window are required.
attribution_modelstringConditionalRequired when sources is set.
attribution_windowintegerConditionalRequired when sources is set. 0 = LTV.
fieldsstring[]NoWhich 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_pageintegerNo1–4000. Default 200.
cursorstringNoPagination cursor from a prior response’s next_cursor.
custom_field_filtersarrayNoAND-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 rangeTypeOperators
profile_field_1 – profile_field_15textequal_to, not_equal_to, contains, not_contains, starts_with, ends_with, contains_word, any, unknown
profile_field_16 – profile_field_25numberequal_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_30dateequal_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 100conversionattributedacross4touchpointsvia‘linear‘returns4rows,eachcrediting100 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.