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.

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

ParameterTypeRequiredDescription
date_rangestringYesPreset like last_30_days, this_month, last_quarter, custom, etc. Use custom with date_start / date_end for arbitrary ranges.
attribution_modelstringYesfirst_touch, last_touch, last_non_direct_touch, linear, linear_paid_ads, u_shaped, first_touch_source_specific, last_touch_source_specific.
attribution_windowintegerYesLookback in days: 1, 7, 14, 30, 60, 90, or 0 for LTV.
attribution_window_typestringYesrelative (default) or absolute.
metricsstring[]YesWhich 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_startstringNoYYYY-MM-DD. Required when date_range is custom, equal_to, or after.
date_endstringNoYYYY-MM-DD. Required when date_range is custom, equal_to, or before.
query_modestringNoprofile (default) or company.
group_bystring[]NoGroup 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.
sourcesstring[]NoRestrict to specific traffic sources (facebook_ads, google_ads, tiktok_ads, linkedin_ads, bing_ads, reddit_ads, taboola_ads, etc.).
filtersobjectNoNested 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 typeOperators
Textequal_to, not_equal_to, contains, not_contains, starts_with, ends_with, contains_word, any, unknown
Numberequal_to, not_equal_to, greater_than, greater_than_or_equal_to, less_than, less_than_or_equal_to, any, unknown
Dateequal_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.