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

> Run the same metrics across two periods (current vs previous) in one call with side-by-side deltas.

A wrapper around `query_ad_metrics` that runs the query twice — current period and the comparison period — and returns both row sets plus a per-metric delta and percent-change. Avoids the double-round-trip of two separate calls.

## When to use

* "How did last week compare to the week before?"
* "Is CPA down vs last month?"
* WoW / MoM / YoY questions.

For comparing **attribution models** (not periods), use [`query_attribution_models`](/mcp/tools/query-attribution-models). For point-in-time queries, use [`query_ad_metrics`](/mcp/tools/query-ad-metrics).

## Parameters

Accepts every parameter `query_ad_metrics` does, plus:

| Parameter             | Type   | Required    | Description                                                |
| --------------------- | ------ | ----------- | ---------------------------------------------------------- |
| `compare_to`          | string | No          | `previous_period` (default), `previous_year`, or `custom`. |
| `previous_date_start` | string | Conditional | Required when `compare_to=custom`. `YYYY-MM-DD`.           |
| `previous_date_end`   | string | Conditional | Required when `compare_to=custom`. `YYYY-MM-DD`.           |

Previous-period semantics:

* `this_*` presets map to their `last_*` counterparts (`this_week` → `last_week`, etc.).
* Trailing windows (`last_7_days`, `last_30_days`, …) shift the same span backward.
* Custom date ranges with `compare_to: previous_year` subtract 365 days from both bounds.

## Output

```json theme={null}
{
  "current":  [{ "source": "facebook_ads", "purchase": 412, "roas": 3.82 }],
  "previous": [{ "source": "facebook_ads", "purchase": 387, "roas": 3.55 }],
  "delta": [
    { "key": "sources=facebook_ads", "metric": "purchase", "current": 412, "previous": 387, "delta": 25, "pct_change": 6.46 },
    { "key": "sources=facebook_ads", "metric": "roas",     "current": 3.82, "previous": 3.55, "delta": 0.27, "pct_change": 7.6 }
  ]
}
```

`pct_change` is `null` when the previous-period value is `0` (avoids divide-by-zero).

## Caveats

Attribution windows are calendar-day-based (UTC). Across DST transitions a 7-day window may span 6d 23h or 7d 1h — mention this when explaining period-over-period changes if the period crosses a DST boundary.