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.

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. For point-in-time queries, use query_ad_metrics.

​
Parameters

Accepts every parameter query_ad_metrics does, plus:
ParameterTypeRequiredDescription
compare_tostringNoprevious_period (default), previous_year, or custom.
previous_date_startstringConditionalRequired when compare_to=custom. YYYY-MM-DD.
previous_date_endstringConditionalRequired 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

{
  "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.