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 session-start tool. Call this once before any analytics question so the agent knows the user’s timezone, currency, configured custom event labels, connected ad accounts, and default attribution model / window. Replaces the legacy “data instructions” prompt-stuffing pattern with a single, cacheable, ~1 KB call.

​
When to use

  • At the start of every chat session before any analytics question.
  • Whenever the user references a custom event by name (“deals”, “lead magnet”) and you need the slot map.
  • To check the default attribution model before running query_ad_metrics.
For per-question lookups about a specific entity, use search_workspace. For tracking-health diagnostics, use get_space_health.

​
Parameters

ParameterTypeRequiredDescription
formatstringNojson (default), csv, or yaml. Single-object payload — CSV flattens to key/value rows.

​
Output shape

{
  "space":   { "id": 123, "name": "Acme Marketing" },
  "team":    { "id": 7, "name": "Acme Inc." },
  "timezone": "America/New_York",
  "currency": "USD",
  "ad_accounts": [
    { "source": "facebook_ads", "id": "act_1234567890", "name": "Acme Meta", "currency": "USD", "status": "active", "last_synced_at": "2026-05-15T14:08:00Z" },
    { "source": "google_ads",   "id": "111-222-3333",   "name": "Acme Google", "currency": "USD", "status": "active", "last_synced_at": "2026-05-15T13:55:00Z" }
  ],
  "custom_event_labels": {
    "custom_event_2": "Deal Created",
    "custom_event_5": "Lead Magnet"
  },
  "default_attribution_model":  "last_touch",
  "default_attribution_window": 30,
  "ai_credit_balance": 14200
}
ai_credit_balance reflects the team’s ai_credits column (shared across every space on the team). default_attribution_model / default_attribution_window surface Cometly’s product defaults — they aren’t currently persisted per-space.

​
Caveats

  • The ai_credit_balance field reflects the team-level balance at request time. Don’t recommend analyze_report (or other credit-charging tools) when the balance is at zero.
  • last_synced_at is best-effort — different ad platforms expose different timestamp columns. Use get_space_health for the canonical freshness check.