Skip to main content
Use it for aggregate questions about marketing performance: spend efficiency, ROAS/CPA, conversion volume, results by ad platform. Period-over-period comparisons go to query_ad_metrics_compare and explicit top-N lists to query_metric_breakdown. 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

Filters

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

Operator vocabulary

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:
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 are the figures each ad platform reports for its own ads. Gross Revenue and Purchases are the conversions Cometly recorded on the site and through connected sources under one attribution model. The model says which set a figure comes from when it presents it.
  • Brand search campaigns: the model is told not to recommend budget scaling on Google branded search — volume is capped by brand awareness, not budget.