query_ad_metrics

The primary tool for any question about marketing performance — spend efficiency, ROAS/CPA, conversion volume, platform comparison. Wraps the same engine that powers Cometly’s report builder and Custom Dashboards.

When to use

Aggregated questions: “What’s my ROAS by source last 30 days?”, “Daily spend trend for Facebook?”, “Top adsets by purchases this month?”
Comparisons across attribution models, windows, sources, or time periods.
Group-by reporting on ad hierarchy, geography, device, browser, or traffic source.

For individual events, use list_events. For per-person journeys, use get_contact.

Parameters

Parameter	Type	Required	Description
`date_range`	string	Yes	Preset like `last_30_days`, `this_month`, `last_quarter`, `custom`, etc. Use `custom` with `date_start` / `date_end` for arbitrary ranges.
`attribution_model`	string	Yes	`first_touch`, `last_touch`, `last_non_direct_touch`, `linear`, `linear_paid_ads`, `u_shaped`, `first_touch_source_specific`, `last_touch_source_specific`.
`attribution_window`	integer	Yes	Lookback in days: `1`, `7`, `14`, `30`, `60`, `90`, or `0` for LTV.
`attribution_window_type`	string	Yes	`relative` (default) or `absolute`.
`metrics`	string[]	Yes	Which metrics to return. Common: `amount_spent`, `impressions`, `clicks`, `link_clicks`, `purchase`, `purchase_amount`, `roas`, `gross_revenue`, `net_profit`, `roi`, `cpm`, `cpc`, `ctr`, `cost_per_purchase`, `average_order_value`, `lead_generated`, `add_to_cart`, `view_content`, `sign_up`, plus `custom_event_1` through `custom_event_50`.
`date_start`	string	No	`YYYY-MM-DD`. Required when `date_range` is `custom`, `equal_to`, or `after`.
`date_end`	string	No	`YYYY-MM-DD`. Required when `date_range` is `custom`, `equal_to`, or `before`.
`query_mode`	string	No	`profile` (default) or `company`.
`group_by`	string[]	No	Group results by one or more dimensions. Time: `day`, `week`, `month`, `quarter`, `year`. Ad hierarchy: `campaign_name`, `adset_name`, `ad_name`, `account_name` (and `_id` variants). Other: `sources`, `country`, `state`, `city`, `device_type`, `browser`, `os`, `url`, `referrer`, `keyword`.
`sources`	string[]	No	Restrict to specific traffic sources (`facebook_ads`, `google_ads`, `tiktok_ads`, `linkedin_ads`, `bing_ads`, `reddit_ads`, `x_ads`, `taboola_ads`, `whop_ads`, etc.).
`filters`	object	No	Nested filter tree. See Filters below.

Filters

Same shape as Cometly’s report builder. Conditions are grouped, and groups are connected by AND / OR:

{
  "connector": "and",
  "groups": [
    {
      "connector": "and",
      "conditions": [
        { "filter": "campaign_name", "operator": "contains",   "value": "spring sale", "start": null, "end": null },
        { "filter": "country",       "operator": "equal_to",   "value": "US",          "start": null, "end": null },
        { "filter": "profile_field_5", "operator": "equal_to", "value": "Premium",     "start": null, "end": null }
      ]
    }
  ]
}

Operator vocabulary

Field type	Operators
Text	`equal_to`, `not_equal_to`, `contains`, `not_contains`, `starts_with`, `ends_with`, `contains_word`, `any`, `unknown`
Number	`equal_to`, `not_equal_to`, `greater_than`, `greater_than_or_equal_to`, `less_than`, `less_than_or_equal_to`, `any`, `unknown`
Date	`equal_to`, `between`, `greater_than`, `less_than`, `age_greater_than`, `age_equal_to`, `age_less_than`, `any`, `unknown`

Filterable slugs (subset)

Demographic & touchpoint: email, email_domain, country, region, city, device_type, os, browser, language, referrer, url, url_parameters, keyword. Ad hierarchy: ad_account_id, ad_campaign_id, ad_set_id, ad_id, plus _name variants. Conversion counts & dates: any standard event name (purchase, lead_generated, etc.) as a numeric count filter, plus _date and _first_date variants. Custom profile fields: profile_field_1 through profile_field_30. The tool description lists the labels and types your Space has configured so the model knows which slot to use for which user-facing label. Lifetime value: ltv.

Example response

For a request grouping purchase, purchase_amount, and roas by sources over the last 30 days, the model gets back something like:

{
  "rows": [
    { "source": "facebook_ads", "purchase": 412, "purchase_amount": 38420.50, "roas": 3.82 },
    { "source": "google_ads",   "purchase": 297, "purchase_amount": 27110.20, "roas": 4.15 },
    { "source": "tiktok_ads",   "purchase":  88, "purchase_amount":  6210.75, "roas": 2.41 }
  ],
  "totals": { "purchase": 797, "purchase_amount": 71741.45, "roas": 3.61 }
}

The model then renders this as a chart, markdown table, or whichever format you asked for.

Caveats

attribution_window: 0 means LTV — the model is instructed to refer to it as “LTV (Lifetime Value)” rather than “0-day” in user-facing responses.
Reported Revenue / Reported Purchases come from Meta’s API and are platform-reported (often inaccurate). The model is instructed not to mention them unless explicitly asked.
Brand search campaigns: the model is told not to recommend budget scaling on Google branded search — volume is capped by brand awareness, not budget.

Get Started

Connecting Clients

Tools

Resources

Prompts

When to use

Parameters

Filters

Operator vocabulary

Filterable slugs (subset)

Example response

Caveats

​When to use

​Parameters

​Filters

​Operator vocabulary

​Filterable slugs (subset)

​Example response

​Caveats

When to use

Parameters

Filters

Operator vocabulary

Filterable slugs (subset)

Example response

Caveats