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

# query_ad_metrics

> Aggregated ad performance metrics from the Cometly report builder — ROAS, CPA, spend, conversions, with grouping, attribution, and filters.

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`](/mcp/tools/list-events). For per-person journeys, use [`get_contact`](/mcp/tools/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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.