MCP tool reference

Every mrkr MCP tool with its scope, parameters, defaults, allowed values, an example call and an example result, plus the conventions for sites, dates, filters, currency, units and pagination.

Markdown
Updated Oct 5, 2026
On this page
  1. Tools at a glance
  2. Conventions
  3. Choosing a site
  4. Dates and time zones
  5. Comparison periods
  6. Filters
  7. Currency and money
  8. Units
  9. Pagination and limits
  10. Freshness
  11. Result format
  12. Connection tools
  13. list_sites
  14. Analytics tools (analytics:read)
  15. get_overview
  16. get_timeseries
  17. get_breakdown
  18. get_sources
  19. get_realtime
  20. get_ai_referrals
  21. get_ai_crawlers
  22. get_outbound_links
  23. get_web_vitals
  24. get_journeys
  25. list_funnels
  26. get_funnel_report
  27. list_annotations
  28. list_campaign_links
  29. Funnels, annotations and campaign links (analytics:write)
  30. create_funnel
  31. update_funnel
  32. delete_funnel
  33. create_annotation
  34. delete_annotation
  35. create_campaign_link
  36. delete_campaign_link
  37. Event tools (events:read)
  38. list_events
  39. get_event
  40. get_conversions
  41. list_event_configs
  42. Event configuration (events:write)
  43. configure_event
  44. Visitor tools (visitors:read)
  45. list_live_visitors
  46. list_visitors
  47. get_visitor
  48. Settings tools (settings:read)
  49. get_settings
  50. Settings changes (settings:write)
  51. update_settings

mrkr's MCP server has 32 tools: 23 read data and 9 change configuration. An assistant only sees the tools its connection has permission for.

Tools at a glance

ToolScopeWhat it returns
list_sitesnoneLists the sites this connection may read and the permissions it was granted.
get_overviewanalytics:readHeadline KPIs for a period, each compared with the previous period of equal length.
get_timeseriesanalytics:readOne point per bucket for the metrics you ask for: daily, hourly or every 15 minutes.
get_breakdownanalytics:readTop values of one dimension with counts and share of the total.
get_sourcesanalytics:readAcquisition sources (Google, ChatGPT, Direct, newsletters) with visits, conversions, purchases, revenue and time to purchase.
get_realtimeanalytics:readVisitors active in the last 5 minutes, with top countries, pages and devices.
get_ai_referralsanalytics:readPeople who arrived from AI assistants (ChatGPT, Perplexity, Claude, Gemini, Copilot), with share, split by assistant, landing pages and a daily trend.
get_ai_crawlersanalytics:readRequests from AI and search crawlers (GPTBot, ClaudeBot, PerplexityBot) by crawler, provider, category and path.
get_outbound_linksanalytics:readClicks on links to other domains, by host, and file downloads, by file type.
get_web_vitalsanalytics:readReal-user Core Web Vitals: p75 and p95 for LCP, INP, CLS, FCP and TTFB, overall and for the 20 pages with the most samples.
get_journeysanalytics:readLanding and exit pages, and the 12 most common page sequences up to 5 steps.
list_funnelsanalytics:readSaved funnels with their ordered steps, exclusions, conversion window, order and breakdown.
get_funnel_reportanalytics:readEvaluates a saved funnel: visitors per step, drop-off, step and overall conversion, time to convert and a daily trend.
create_funnelanalytics:writeSaves a new funnel of 2 to 10 page or event steps, with the same validation as the dashboard.
update_funnelanalytics:writeChanges a saved funnel by its exact id. Omitted fields keep their value; steps, when given, replace all steps.
delete_funnelanalytics:writePermanently deletes a saved funnel by its exact id. Collected data is not affected.
list_annotationsanalytics:readDated chart notes, such as "Launched on Product Hunt", in a period.
create_annotationanalytics:writeAdds a dated note to the site's charts, such as a launch, campaign or outage.
delete_annotationanalytics:writePermanently deletes a chart annotation by its exact id.
list_campaign_linksanalytics:readSaved campaign (UTM) links, newest first, with the full tagged URL.
create_campaign_linkanalytics:writeSaves a campaign (UTM) link and returns the tagged URL to share.
delete_campaign_linkanalytics:writeDeletes a saved campaign link by its exact id.
list_eventsevents:readCustom events with totals, unique visitors, first and last seen, and conversion settings, plus overall event totals.
get_eventevents:readOne event in depth: volume, unique visitors, daily trend, property values, recent samples and revenue in one currency.
get_conversionsevents:readEvery event configured as a conversion (goal): completions, unique converters, conversion rate, revenue and target.
list_event_configsevents:readSaved event settings (label, conversion flag, revenue property, target, hidden), including events configured before they first fired.
configure_eventevents:writeMarks or unmarks a custom event as a conversion (goal), and sets its label, target, revenue property, reviewed or hidden flags. Returns the saved configuration.
list_live_visitorsvisitors:readIndividual visitors active in the last 5 minutes, with source, device and approximate location.
list_visitorsvisitors:readIndividual visitors in a period, most recent first, with visits, pages, source, location, device and whether they converted.
get_visitorvisitors:readOne visitor's retained visits on this site, newest first, with purchase totals per currency and time from first visit to first purchase.
get_settingssettings:readA site's tracking settings: name, domain, cookieless or cookie mode, session replay and excluded paths.
update_settingssettings:writeChanges a site's name, session replay, replay sample rate or excluded paths, and returns the saved settings.

Conventions

These rules apply to every tool. Tool sections below link back here instead of repeating them.

Choosing a site

Tools take an optional site_id. Pass the ID from list_sites (site_k3x9q2mf) or the site's domain (example.com). If the connection has exactly one site, you can leave it out. With several sites and no site_id, the tool fails and lists the sites you can use. There is no fallback to the site open in the dashboard, and sites not approved for the connection are never reachable.

Dates and time zones

rangeCovers
todayToday so far, in timezone.
yesterdayYesterday, midnight to midnight in timezone.
24hThe rolling 24 hours ending now.
7d, 30d, 90dThat many calendar days ending today, today included.
12mThe last 365 days, today included.
customfrom to to, both YYYY-MM-DD and inclusive. to defaults to today. At most 366 days.
Default 30d. Setting from or to implies custom; combining them with another preset is an error.

timezone is an IANA name, default UTC. Pass the user's time zone so day boundaries match their dashboard. Every result echoes the resolved period: { preset, from, to, timezone, days, includes_today, rolling }. Report those dates, not the ones you guessed.

September 2026 in Zurichjson
{
  "from": "2026-09-01",
  "to": "2026-09-30",
  "timezone": "Europe/Zurich"
}

Comparison periods

get_overview compares every metric with the previous period of equal length, ending just before the current one starts, and returns it as compare_period. A 30d period compares with the 30 days before it. For any other comparison, such as this September against last September, call the tool twice with custom dates and compare the results.

Filters

filters maps a dimension to an array of exact values. Values within one dimension are OR, dimensions are AND. Up to 20 values per dimension, each up to 256 characters, and at most 70 expanded values in total. Get exact values from get_breakdown or get_sources first.

DimensionExample values
countryUS, DE (ISO 3166-1 alpha-2)
region, cityCalifornia, Zurich
devicedesktop, mobile, tablet
browser, osChrome, Safari, macOS, iOS
sourceGoogle, Direct, ChatGPT, as returned by get_sources
medium, utm_source, utm_medium, utm_campaignemail, newsletter, cpc, spring_launch
entry_path, exit_path/pricing
referrernews.ycombinator.com
language, timezoneen-US, Europe/Berlin
eventsignup_completed: visits that fired this custom event
(none) matches an empty value, for example visits with no campaign.
Mobile visitors from Google or Bing in the US or Canadajson
{
  "filters": {
    "device": [
      "mobile"
    ],
    "source": [
      "Google",
      "Bing"
    ],
    "country": [
      "US",
      "CA"
    ]
  }
}

Currency and money

Money is in major currency units: 49 means 49.00, never cents. Each call reports exactly one currency. Without currency, mrkr uses the site's main currency and lists the others in available_currencies. Amounts in different currencies are never converted or added together; call again with "currency": "EUR" to report euros. Revenue with no valid currency code is reported as unknown. Refunds are negative and reduce totals.

Units

FieldUnit
change_pctPercent change vs compare_period (8.8 = +8.8%). null when the previous value was 0.
bounce_rate, conversion_rate, share, conv_from_*, rateFraction from 0 to 1
*_secondsSeconds
*_msMilliseconds
ts, first_seen, last_seen, started_at, *_at (numbers)Epoch milliseconds
start, observed_atISO 8601 string, UTC
dateYYYY-MM-DD in the period's time zone
Web Vitals p75, p95Milliseconds, except CLS (unitless)
Decimals are rounded to 4 places. Most results also carry a units object that says this inline.

Pagination and limits

List tools take limit (1 to 100) and, where offered, offset (0 to 1000). Results carry returned and next_offset, which is null on the last page. Ranked lists also carry available_items and source_truncated; true means mrkr capped the ranking before paging, so the list is a top N, not a complete export.

Freshness

Periods that include today refresh within about 10 seconds. Past periods are cached for 60 seconds. get_realtime and list_live_visitors are never cached and cover the last 5 minutes.

Result format

Every tool returns a one-line plain-English summary as the first text item, the full JSON as the second text item, and the same JSON as structuredContent. The examples on this page show that JSON. Inputs are strict: unknown fields are rejected. A failed call returns isError: true with a message that says how to fix it, for example site_id is required. Accessible sites: site_k3x9q2mf (example.com), .... Results are capped at 200,000 bytes. See errors.

Connection tools

list_sites

Lists the sites this connection may read and the permissions it was granted. When to use: Call it first. It gives the site_id other tools take and tells you which tools are available.

Scope: none, any connection. Type: read-only.

ParameterTypeDefaultNotes
limitinteger251 to 100.
offsetinteger00 to 1000. Pass the previous next_offset.
list_sites argumentsjson
{}
list_sites result data (example, lists shortened)json
{
  "items": [
    {
      "site_id": "site_k3x9q2mf",
      "name": "Example",
      "domain": "example.com",
      "role": "owner"
    }
  ],
  "returned": 1,
  "available_items": 1,
  "source_truncated": false,
  "next_offset": null,
  "permissions": [
    "analytics:read",
    "events:read"
  ]
}
  • Only sites you approved for this connection AND can still access in mrkr are listed.
  • role is owner, admin or member. Write tools need owner or admin.

Analytics tools (analytics:read)

get_overview

Headline KPIs for a period, each compared with the previous period of equal length. When to use: The first data call for "how is my site doing", "is traffic up" or "what was revenue last month".

Scope: analytics:read. Type: read-only.

ParameterTypeDefaultNotes
site_id, range, from, to, timezone, filterssharedSee notesSite: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC). Filters: optional.
currencystringMain currencyISO 4217 code such as USD, or unknown. Never converted or combined.
get_overview argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "timezone": "Europe/Zurich",
  "currency": "USD"
}
get_overview result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "period": {
    "preset": "custom",
    "from": "2026-09-01",
    "to": "2026-09-30",
    "timezone": "Europe/Zurich",
    "days": 30,
    "includes_today": false,
    "rolling": false
  },
  "compare_period": {
    "from": "2026-08-02",
    "to": "2026-08-31"
  },
  "metrics": {
    "visitors": {
      "value": 4210,
      "previous": 3870,
      "change_pct": 8.7855
    },
    "visits": {
      "value": 5630,
      "previous": 5120,
      "change_pct": 9.9609
    },
    "pageviews": {
      "value": 13980,
      "previous": 12550,
      "change_pct": 11.3944
    },
    "pages_per_visit": {
      "value": 2.4831,
      "previous": 2.4512,
      "change_pct": 1.3014
    },
    "bounce_rate": {
      "value": 0.41,
      "previous": 0.44,
      "change_pct": -6.8182
    },
    "avg_visit_duration_seconds": {
      "value": 96.4,
      "previous": 91.2,
      "change_pct": 5.7018
    },
    "conversions": {
      "value": 212,
      "previous": 190,
      "change_pct": 11.5789
    },
    "conversion_rate": {
      "value": 0.0377,
      "previous": 0.0371,
      "change_pct": 1.6173
    },
    "purchases": {
      "value": 80,
      "previous": 70,
      "change_pct": 14.2857
    },
    "revenue": {
      "value": 3920,
      "previous": 3410,
      "change_pct": 14.956
    }
  },
  "currency": "USD",
  "available_currencies": [
    "USD",
    "EUR"
  ],
  "revenue_detail": {
    "avg_order_value": 49,
    "revenue_per_visitor": 0.9311,
    "attributed": 3720,
    "unattributed": 200,
    "avg_time_to_purchase_seconds": 259200
  },
  "units": {
    "change_pct": "relative change vs compare_period in percent; null when the previous value was 0",
    "bounce_rate": "fraction of visits with one pageview (0 to 1)",
    "conversion_rate": "converting visits / visits (0 to 1)",
    "conversions": "visits with a purchase or a configured conversion event",
    "money": "major_currency_units",
    "avg_visit_duration_seconds": "seconds"
  },
  "freshness": "Ranges that include today refresh within about 10 seconds; past ranges are cached for 60 seconds."
}
  • compare_period ends the day before period starts and has the same length.
  • visitors counts distinct people over the whole period. It is not the sum of daily visitors.

get_timeseries

One point per bucket for the metrics you ask for: daily, hourly or every 15 minutes. When to use: Trends and "when did it change" questions, or charting a launch day.

Scope: analytics:read. Type: read-only.

ParameterTypeDefaultNotes
site_id, range, from, to, timezone, filterssharedSee notesSite: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC). Filters: optional.
currencystringMain currencyISO 4217 code such as USD, or unknown. Never converted or combined.
metricsstring[]["visitors"]1 to 6 of visitors, visits, pageviews, bounce_rate, avg_visit_duration_seconds, revenue.
intervalstringhour up to 2 days, else day15m, hour or day. 15m and hour support only visitors and revenue, up to 744 buckets.
get_timeseries argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "range": "yesterday",
  "timezone": "Europe/Zurich",
  "metrics": [
    "visitors",
    "revenue"
  ],
  "interval": "15m",
  "currency": "USD"
}
get_timeseries result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "period": {
    "preset": "yesterday",
    "from": "2026-10-04",
    "to": "2026-10-04",
    "timezone": "Europe/Zurich",
    "days": 1,
    "includes_today": false,
    "rolling": false
  },
  "interval": "15m",
  "metrics": [
    "visitors",
    "revenue"
  ],
  "currency": "USD",
  "available_currencies": [
    "USD"
  ],
  "points": [
    {
      "start": "2026-10-03T22:00:00.000Z",
      "visitors": 4,
      "revenue": 0
    },
    {
      "start": "2026-10-03T22:15:00.000Z",
      "visitors": 6,
      "revenue": 49
    }
  ],
  "units": {
    "bounce_rate": "fraction 0 to 1",
    "avg_visit_duration_seconds": "seconds",
    "revenue": "major_currency_units",
    "visitors": "unique within each bucket"
  },
  "freshness": "Ranges that include today refresh within about 10 seconds; past ranges are cached for 60 seconds."
}
  • Daily points carry date (YYYY-MM-DD in timezone). Sub-day points carry start, an ISO 8601 UTC timestamp on fixed UTC-aligned intervals.
  • 744 buckets is 31 days hourly or about 7 days at 15 minutes.
  • Visitors are unique per bucket. Adding buckets up over-counts returning people; use get_overview for the total.

get_breakdown

Top values of one dimension with counts and share of the total. When to use: "Top pages", "which countries", "which campaigns", and finding exact values to use in filters. For sources with revenue, use get_sources.

Scope: analytics:read. Type: read-only.

ParameterTypeDefaultNotes
site_id, range, from, to, timezone, filterssharedSee notesSite: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC). Filters: optional.
dimensionstringRequiredpage, entry_page, exit_page, referrer, medium, utm_source, utm_medium, utm_campaign, country, region, city, device, browser, os or language.
metricstringvisitorsvisitors (unique people), visits (sessions) or pageviews.
limitinteger101 to 100.
get_breakdown argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "timezone": "Europe/Zurich",
  "dimension": "country",
  "limit": 3
}
get_breakdown result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "period": {
    "preset": "custom",
    "from": "2026-09-01",
    "to": "2026-09-30",
    "timezone": "Europe/Zurich",
    "days": 30,
    "includes_today": false,
    "rolling": false
  },
  "dimension": "country",
  "metric": "visitors",
  "total": 4210,
  "items": [
    {
      "value": "US",
      "count": 1520,
      "share": 0.361
    },
    {
      "value": "DE",
      "count": 610,
      "share": 0.1449
    },
    {
      "value": "CH",
      "count": 402,
      "share": 0.0955
    }
  ],
  "returned": 3,
  "max_limit": 100,
  "notes": [
    "A visitor can appear under several values, so shares can add up to more than 100%."
  ]
}
  • page returns at most 20 rows; other dimensions up to 100. region rows add country, city rows add region and country.
  • With filters, page counts landing pages, because individual pageviews cannot be segmented. (none) means the value was empty, such as direct visits with no referrer.

get_sources

Acquisition sources (Google, ChatGPT, Direct, newsletters) with visits, conversions, purchases, revenue and time to purchase. When to use: "Where does traffic come from" and "which channels make money".

Scope: analytics:read. Type: read-only.

ParameterTypeDefaultNotes
site_id, range, from, to, timezone, filterssharedSee notesSite: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC). Filters: optional.
currencystringMain currencyISO 4217 code such as USD, or unknown. Never converted or combined.
sortstringvisitorsvisitors, visits, conversions or revenue.
limitinteger101 to 100.
offsetinteger00 to 1000. Pass the previous next_offset.
get_sources argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "timezone": "Europe/Zurich",
  "currency": "USD",
  "sort": "revenue",
  "limit": 2
}
get_sources result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "period": {
    "preset": "custom",
    "from": "2026-09-01",
    "to": "2026-09-30",
    "timezone": "Europe/Zurich",
    "days": 30,
    "includes_today": false,
    "rolling": false
  },
  "sort": "revenue",
  "currency": "USD",
  "available_currencies": [
    "USD",
    "EUR"
  ],
  "totals": {
    "visitors": 4210,
    "visits": 5630,
    "conversions": 212,
    "conversion_rate": 0.0377,
    "purchases": 80,
    "revenue": 3920,
    "attributed_revenue": 3720,
    "unattributed_revenue": 200,
    "avg_order_value": 49,
    "revenue_per_visitor": 0.9311
  },
  "items": [
    {
      "source": "Google",
      "visitors": 1840,
      "visits": 2410,
      "pageviews": 6120,
      "conversions": 96,
      "conversion_rate": 0.0398,
      "purchases": 40,
      "revenue": 1960,
      "revenue_per_visit": 0.8133,
      "avg_time_to_purchase_seconds": 172800
    }
  ],
  "returned": 2,
  "available_items": 14,
  "source_truncated": false,
  "next_offset": 2,
  "attribution": "session",
  "units": {
    "money": "major_currency_units",
    "conversion_rate": "converting visits / visits (0 to 1)"
  },
  "notes": [
    "Totals include sources beyond this page."
  ]
}
  • Revenue belongs to the source of the visit that recorded it. Revenue with no matching visit is unattributed_revenue and appears as the source Unattributed.

get_realtime

Visitors active in the last 5 minutes, with top countries, pages and devices. When to use: "How many people are on the site right now". Aggregates only; individual visitors are in list_live_visitors.

Scope: analytics:read. Type: read-only.

ParameterTypeDefaultNotes
site_id, filterssharedSee notesSite: ID or domain, optional with one site. Filters: optional.
get_realtime argumentsjson
{
  "site_id": "site_k3x9q2mf"
}
get_realtime result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "observed_at": "2026-10-05T09:00:30.000Z",
  "active_window_seconds": 300,
  "active_visitors": 23,
  "countries": 7,
  "by_country": [
    {
      "key": "US",
      "value": 9
    }
  ],
  "by_page": [
    {
      "key": "/pricing",
      "value": 6
    }
  ],
  "by_device": [
    {
      "key": "desktop",
      "value": 15
    }
  ]
}
  • Never cached. Takes no date range. Lists hold up to 8 countries, 8 pages and 4 devices.

get_ai_referrals

People who arrived from AI assistants (ChatGPT, Perplexity, Claude, Gemini, Copilot), with share, split by assistant, landing pages and a daily trend. When to use: "How much traffic do AI assistants send us". For crawler requests use get_ai_crawlers.

Scope: analytics:read. Type: read-only.

ParameterTypeDefaultNotes
site_id, range, from, to, timezone, filterssharedSee notesSite: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC). Filters: optional.
get_ai_referrals argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "timezone": "Europe/Zurich"
}
get_ai_referrals result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "period": {
    "preset": "custom",
    "from": "2026-09-01",
    "to": "2026-09-30",
    "timezone": "Europe/Zurich",
    "days": 30,
    "includes_today": false,
    "rolling": false
  },
  "visitors": 186,
  "visits": 214,
  "site_visitors": 4210,
  "share": 0.0442,
  "by_assistant": [
    {
      "key": "ChatGPT",
      "visitors": 121,
      "visits": 140
    }
  ],
  "landing_pages": [
    {
      "key": "/blog/cookieless-analytics",
      "value": 64
    }
  ],
  "daily_visits": [
    {
      "date": "2026-09-01",
      "value": 5
    }
  ],
  "population": "humans referred by AI assistants"
}

get_ai_crawlers

Requests from AI and search crawlers (GPTBot, ClaudeBot, PerplexityBot) by crawler, provider, category and path. When to use: "Is GPTBot crawling us", "which pages do AI crawlers fetch". Counts requests, never visitors.

Scope: analytics:read. Type: read-only.

ParameterTypeDefaultNotes
site_id, range, from, to, timezonesharedSee notesSite: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC). timezone: Accepted but ignored. Days are always UTC.
get_ai_crawlers argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "range": "30d"
}
get_ai_crawlers result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "period": {
    "preset": "30d",
    "from": "2026-09-06",
    "to": "2026-10-05",
    "timezone": "UTC",
    "days": 30,
    "includes_today": true,
    "rolling": false
  },
  "requests": 9120,
  "by_crawler": [
    {
      "name": "GPTBot",
      "hits": 3110,
      "provider": "OpenAI",
      "category": "training"
    }
  ],
  "by_category": [
    {
      "category": "training",
      "hits": 5200
    },
    {
      "category": "search",
      "hits": 2700
    },
    {
      "category": "assistant",
      "hits": 1220
    }
  ],
  "top_paths": [
    {
      "key": "/docs/get-started/install",
      "value": 410
    }
  ],
  "daily_requests": [
    {
      "date": "2026-09-06",
      "value": 288
    }
  ],
  "population": "crawler requests, never counted as visitors"
}
  • Takes no filters. Lists hold up to 30 crawlers and 15 paths. category is assistant, search or training.

Clicks on links to other domains, by host, and file downloads, by file type. When to use: "Where do visitors leave to", "how many PDF downloads". mrkr never opens the destination URLs.

Scope: analytics:read. Type: read-only.

ParameterTypeDefaultNotes
site_id, range, from, to, timezone, filterssharedSee notesSite: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC). Filters: optional.
get_outbound_links argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "timezone": "Europe/Zurich"
}
get_outbound_links result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "period": {
    "preset": "custom",
    "from": "2026-09-01",
    "to": "2026-09-30",
    "timezone": "Europe/Zurich",
    "days": 30,
    "includes_today": false,
    "rolling": false
  },
  "outbound": [
    {
      "host": "github.com",
      "clicks": 312,
      "top_href": "https://github.com/example/sdk"
    }
  ],
  "downloads": [
    {
      "ext": "pdf",
      "clicks": 87
    }
  ],
  "outbound_total": 640,
  "download_total": 112
}

get_web_vitals

Real-user Core Web Vitals: p75 and p95 for LCP, INP, CLS, FCP and TTFB, overall and for the 20 pages with the most samples. When to use: "Is the site slow", "which pages have bad LCP on mobile" (add filters: { "device": ["mobile"] }).

Scope: analytics:read. Type: read-only.

ParameterTypeDefaultNotes
site_id, range, from, to, timezone, filterssharedSee notesSite: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC). Filters: optional.
get_web_vitals argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "timezone": "Europe/Zurich",
  "filters": {
    "device": [
      "mobile"
    ]
  }
}
get_web_vitals result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "period": {
    "preset": "custom",
    "from": "2026-09-01",
    "to": "2026-09-30",
    "timezone": "Europe/Zurich",
    "days": 30,
    "includes_today": false,
    "rolling": false
  },
  "metrics": [
    {
      "metric": "LCP",
      "unit": "ms",
      "samples": 1830,
      "p75": 2380,
      "p95": 4120
    },
    {
      "metric": "CLS",
      "unit": "unitless",
      "samples": 1790,
      "p75": 0.04,
      "p95": 0.17
    }
  ],
  "pages": [
    {
      "path": "/",
      "samples": 640,
      "metrics": [
        {
          "metric": "LCP",
          "unit": "ms",
          "samples": 210,
          "p75": 2100,
          "p95": 3500
        }
      ]
    }
  ],
  "sampled": false,
  "sample_limit": 10000,
  "rows_analyzed": 8120,
  "page_limit": 20
}
  • Uses the latest 10,000 samples in the period (sampled: true if there were more). Metrics with no samples return null, never a guess.

get_journeys

Landing and exit pages, and the 12 most common page sequences up to 5 steps. When to use: "What do people read before pricing", "where do visits end".

Scope: analytics:read. Type: read-only.

ParameterTypeDefaultNotes
site_id, range, from, to, timezone, filterssharedSee notesSite: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC). Filters: optional.
depthinteger3Pages per path, 1 to 5.
get_journeys argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "timezone": "Europe/Zurich",
  "depth": 3
}
get_journeys result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "period": {
    "preset": "custom",
    "from": "2026-09-01",
    "to": "2026-09-30",
    "timezone": "Europe/Zurich",
    "days": 30,
    "includes_today": false,
    "rolling": false
  },
  "entry_exit": {
    "entries": [
      {
        "key": "/",
        "value": 2010,
        "share": 0.357
      }
    ],
    "exits": [
      {
        "key": "/pricing",
        "value": 980,
        "share": 0.1741
      }
    ],
    "total": 5630
  },
  "paths": {
    "paths": [
      {
        "pages": [
          "/",
          "/pricing",
          "/signup"
        ],
        "count": 142,
        "share": 0.0696
      }
    ],
    "depth": 3,
    "sessions_analyzed": 2040,
    "avg_depth": 2.6,
    "sampled": false
  },
  "top_paths_limit": 12
}
  • Entries and exits count visits, top 10 each. Paths come from the most recent 4,000 multi-page visits; sampled: true means the period had more.

list_funnels

Saved funnels with their ordered steps, exclusions, conversion window, order and breakdown. When to use: Find a funnel_id for get_funnel_report. Steps come back in the same shape create_funnel and update_funnel accept.

Scope: analytics:read. Type: read-only.

ParameterTypeDefaultNotes
site_idsharedSee notesSite: ID or domain, optional with one site.
limitinteger251 to 100.
offsetinteger00 to 1000. Pass the previous next_offset.
list_funnels argumentsjson
{
  "site_id": "site_k3x9q2mf"
}
list_funnels result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "items": [
    {
      "id": "fnl_3b8e51c2a9d0",
      "name": "Signup",
      "steps": [
        {
          "type": "page",
          "value": "/pricing",
          "match": "exact",
          "label": "Pricing"
        },
        {
          "type": "event",
          "value": "signup_completed",
          "match": "exact",
          "label": "Signup"
        }
      ],
      "exclusions": [],
      "conversion_window": {
        "value": 14,
        "unit": "day"
      },
      "order": "sequential",
      "breakdown": null
    }
  ],
  "returned": 1,
  "available_items": 1,
  "source_truncated": false,
  "next_offset": null
}

get_funnel_report

Evaluates a saved funnel: visitors per step, drop-off, step and overall conversion, time to convert and a daily trend. When to use: "Where do people drop out of signup", "did the checkout change help".

Scope: analytics:read. Type: read-only.

ParameterTypeDefaultNotes
site_id, range, from, to, timezone, filterssharedSee notesSite: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC). Filters: optional.
funnel_idstringRequiredAn id from list_funnels or create_funnel.
get_funnel_report argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "timezone": "Europe/Zurich",
  "funnel_id": "fnl_3b8e51c2a9d0"
}
get_funnel_report result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "period": {
    "preset": "custom",
    "from": "2026-09-01",
    "to": "2026-09-30",
    "timezone": "Europe/Zurich",
    "days": 30,
    "includes_today": false,
    "rolling": false
  },
  "funnel": {
    "id": "fnl_3b8e51c2a9d0",
    "name": "Signup",
    "steps": [
      {
        "type": "page",
        "value": "/pricing",
        "match": "exact",
        "label": "Pricing"
      },
      {
        "type": "event",
        "value": "signup_completed",
        "match": "exact",
        "label": "Signup"
      }
    ],
    "exclusions": [],
    "conversion_window": {
      "value": 14,
      "unit": "day"
    },
    "order": "sequential",
    "breakdown": null
  },
  "steps": [
    {
      "index": 0,
      "name": "Pricing",
      "hint": "/pricing",
      "visitors": 1200,
      "dropped": 0,
      "conv_from_prev": 1,
      "conv_from_top": 1
    },
    {
      "index": 1,
      "name": "Signup",
      "hint": "signup_completed",
      "visitors": 198,
      "dropped": 1002,
      "conv_from_prev": 0.165,
      "conv_from_top": 0.165
    }
  ],
  "entrants": 1200,
  "converters": 198,
  "conversion_rate": 0.165,
  "breakdown": null,
  "breakdown_prop": null,
  "time_to_convert": {
    "median_ms": 540000,
    "p90_ms": 86400000,
    "count": 198,
    "buckets": [
      {
        "label": "< 1 min",
        "from_ms": 0,
        "to_ms": 60000,
        "count": 12
      }
    ]
  },
  "trend": [
    {
      "date": "2026-09-01",
      "entrants": 40,
      "converters": 6,
      "rate": 0.15
    }
  ],
  "excluded": 0,
  "truncated": false,
  "order_mode": "sequential",
  "window_ms": 1209600000,
  "units": {
    "conversion_rate": "fraction 0 to 1",
    "counts": "unique visitors"
  }
}
  • dropoff_visitor_samples (visitor IDs that stalled at each step) is added only when the connection also has visitors:read.
  • truncated: true means a row budget was reached and every number is a lower bound. Narrow the period.

list_annotations

Dated chart notes, such as "Launched on Product Hunt", in a period. When to use: Explaining spikes and drops before guessing at causes.

Scope: analytics:read. Type: read-only.

ParameterTypeDefaultNotes
site_id, range, from, to, timezonesharedSee notesSite: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC).
list_annotations argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "timezone": "Europe/Zurich"
}
list_annotations result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "period": {
    "preset": "custom",
    "from": "2026-09-01",
    "to": "2026-09-30",
    "timezone": "Europe/Zurich",
    "days": 30,
    "includes_today": false,
    "rolling": false
  },
  "items": [
    {
      "id": "ann_4c2e9a7b1d03",
      "date": "2026-09-15",
      "label": "Launched on Product Hunt"
    }
  ]
}

Saved campaign (UTM) links, newest first, with the full tagged URL. When to use: "Which campaign links did we create". Measure their traffic with get_breakdown on utm_campaign.

Scope: analytics:read. Type: read-only.

ParameterTypeDefaultNotes
site_idsharedSee notesSite: ID or domain, optional with one site.
limitinteger251 to 100.
offsetinteger00 to 1000. Pass the previous next_offset.
list_campaign_links argumentsjson
{
  "site_id": "site_k3x9q2mf"
}
list_campaign_links result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "items": [
    {
      "id": "utm_9d4a2f6c1e85",
      "label": "October newsletter",
      "url": "https://example.com/pricing?utm_source=newsletter&utm_medium=email&utm_campaign=october_update",
      "destination_url": "https://example.com/pricing",
      "utm_source": "newsletter",
      "utm_medium": "email",
      "utm_campaign": "october_update",
      "utm_term": null,
      "utm_content": null,
      "created_at": "2026-10-05T09:12:00.000Z"
    }
  ],
  "returned": 1,
  "next_offset": null
}

create_funnel

Saves a new funnel of 2 to 10 page or event steps, with the same validation as the dashboard. When to use: "Build a funnel from /pricing to signup to purchase". Confirm with the user first, then call get_funnel_report with the returned id.

Scope: analytics:write. Type: write, changes live configuration.

ParameterTypeDefaultNotes
site_idsharedSee notesSite: ID or domain, optional with one site.
namestringRequiredUp to 80 characters.
stepsobject[]Required2 to 10 ordered steps. See the step fields below.
exclusionsobject[]NoneUp to 5 actions that remove a visitor when done between two steps.
conversion_windowobject14 days{ value, unit }: value 1 to 365, unit minute, hour, day or week. Time from first to last step.
orderstringsequentialsequential (in order, other activity allowed), strict (no other funnel step in between) or any.
breakdownstring or nullNoneSplit by device, browser, os, source, medium, country, region, city, utm_source, utm_medium, utm_campaign, entry_path, exit_path, language or prop:<event property>. null removes it.
create_funnel argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "name": "Signup",
  "steps": [
    {
      "type": "page",
      "value": "/pricing"
    },
    {
      "type": "event",
      "value": "signup_completed",
      "label": "Signup"
    }
  ],
  "conversion_window": {
    "value": 14,
    "unit": "day"
  }
}
create_funnel result data (example, lists shortened)json
{
  "ok": true,
  "site_id": "site_k3x9q2mf",
  "funnel": {
    "id": "fnl_3b8e51c2a9d0",
    "name": "Signup",
    "steps": [
      {
        "type": "page",
        "value": "/pricing",
        "match": "exact",
        "label": "Pricing"
      },
      {
        "type": "event",
        "value": "signup_completed",
        "match": "exact",
        "label": "Signup"
      }
    ],
    "exclusions": [],
    "conversion_window": {
      "value": 14,
      "unit": "day"
    },
    "order": "sequential",
    "breakdown": null
  }
}
  • Each step: type (page or event), value (a path such as /pricing, or a custom event name, up to 200 characters), match (exact default, contains, prefix, regex), optional alternatives (up to 5 more paths or names that also count), conditions (up to 5 property checks: key, op of eq, neq, contains, gt, lt, set, unset, and value) and label (up to 80 characters).
  • Each exclusion has the same target fields plus from_step and to_step (1-based, default the whole funnel).
  • Not idempotent: retrying a create saves a second funnel. Needs owner or admin. Audited.

update_funnel

Changes a saved funnel by its exact id. Omitted fields keep their value; steps, when given, replace all steps. When to use: "Add a checkout step to the signup funnel". The id stays the same, so shared links keep working. Confirm with the user first.

Scope: analytics:write. Type: write, changes live configuration.

ParameterTypeDefaultNotes
site_idsharedSee notesSite: ID or domain, optional with one site.
funnel_idstringRequiredExact id from list_funnels.
namestringUnchangedUp to 80 characters.
stepsobject[]Unchanged2 to 10 ordered steps. See the step fields below.
exclusionsobject[]NoneUp to 5 actions that remove a visitor when done between two steps.
conversion_windowobject14 days{ value, unit }: value 1 to 365, unit minute, hour, day or week. Time from first to last step.
orderstringsequentialsequential (in order, other activity allowed), strict (no other funnel step in between) or any.
breakdownstring or nullNoneSplit by device, browser, os, source, medium, country, region, city, utm_source, utm_medium, utm_campaign, entry_path, exit_path, language or prop:<event property>. null removes it.
update_funnel argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "funnel_id": "fnl_3b8e51c2a9d0",
  "order": "strict",
  "conversion_window": {
    "value": 7,
    "unit": "day"
  }
}
update_funnel result data (example, lists shortened)json
{
  "ok": true,
  "site_id": "site_k3x9q2mf",
  "changed_fields": [
    "conversion_window",
    "order"
  ],
  "funnel": {
    "id": "fnl_3b8e51c2a9d0",
    "name": "Signup",
    "steps": [
      {
        "type": "page",
        "value": "/pricing",
        "match": "exact",
        "label": "Pricing"
      },
      {
        "type": "event",
        "value": "signup_completed",
        "match": "exact",
        "label": "Signup"
      }
    ],
    "exclusions": [],
    "conversion_window": {
      "value": 7,
      "unit": "day"
    },
    "order": "strict",
    "breakdown": null
  }
}
  • Needs owner or admin. Audited.

delete_funnel

Permanently deletes a saved funnel by its exact id. Collected data is not affected. When to use: Only when the user asks to remove a funnel. There is no name matching and no undo.

Scope: analytics:write. Type: write, changes live configuration.

ParameterTypeDefaultNotes
site_idsharedSee notesSite: ID or domain, optional with one site.
funnel_idstringRequiredExact id from list_funnels.
delete_funnel argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "funnel_id": "fnl_3b8e51c2a9d0"
}
delete_funnel result data (example, lists shortened)json
{
  "ok": true,
  "site_id": "site_k3x9q2mf",
  "deleted": {
    "id": "fnl_3b8e51c2a9d0",
    "name": "Signup",
    "steps": [
      {
        "type": "page",
        "value": "/pricing",
        "match": "exact",
        "label": "Pricing"
      },
      {
        "type": "event",
        "value": "signup_completed",
        "match": "exact",
        "label": "Signup"
      }
    ],
    "exclusions": [],
    "conversion_window": {
      "value": 14,
      "unit": "day"
    },
    "order": "sequential",
    "breakdown": null
  }
}
  • Needs owner or admin. Audited.

create_annotation

Adds a dated note to the site's charts, such as a launch, campaign or outage. When to use: "Mark today's newsletter on the chart". Confirm with the user first.

Scope: analytics:write. Type: write, changes live configuration.

ParameterTypeDefaultNotes
site_idsharedSee notesSite: ID or domain, optional with one site.
datestringRequiredYYYY-MM-DD.
labelstringRequired1 to 120 characters.
create_annotation argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "date": "2026-10-05",
  "label": "October newsletter sent"
}
create_annotation result data (example, lists shortened)json
{
  "ok": true,
  "site_id": "site_k3x9q2mf",
  "annotation": {
    "id": "ann_7f1b3c9e2a40",
    "date": "2026-10-05",
    "label": "October newsletter sent"
  }
}
  • Not idempotent: retrying adds a second note. Needs owner or admin. Audited.

delete_annotation

Permanently deletes a chart annotation by its exact id. When to use: Only when the user asks to remove a note. Get the id from list_annotations.

Scope: analytics:write. Type: write, changes live configuration.

ParameterTypeDefaultNotes
site_idsharedSee notesSite: ID or domain, optional with one site.
annotation_idstringRequiredExact id from list_annotations.
delete_annotation argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "annotation_id": "ann_7f1b3c9e2a40"
}
delete_annotation result data (example, lists shortened)json
{
  "ok": true,
  "site_id": "site_k3x9q2mf",
  "deleted": {
    "id": "ann_7f1b3c9e2a40",
    "date": "2026-10-05",
    "label": "October newsletter sent"
  }
}
  • Needs owner or admin. Audited.

Saves a campaign (UTM) link and returns the tagged URL to share. When to use: "Make a link for the October newsletter". Visits through it are reported under these utm_* values.

Scope: analytics:write. Type: write, changes live configuration.

ParameterTypeDefaultNotes
site_idsharedSee notesSite: ID or domain, optional with one site.
destination_urlstringRequiredFull landing page URL with https://, up to 2,000 characters. Existing query parameters are kept.
utm_sourcestringRequiredUp to 80 characters, such as newsletter.
utm_mediumstringRequiredUp to 80 characters, such as email.
utm_campaignstringRequiredUp to 120 characters, such as october_update.
utm_termstringNoneOptional keyword, up to 80 characters.
utm_contentstringNoneOptional variant, up to 120 characters.
labelstringNoneOptional name to find it later, up to 120 characters.
create_campaign_link argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "destination_url": "https://example.com/pricing",
  "utm_source": "newsletter",
  "utm_medium": "email",
  "utm_campaign": "october_update",
  "label": "October newsletter"
}
create_campaign_link result data (example, lists shortened)json
{
  "ok": true,
  "site_id": "site_k3x9q2mf",
  "link": {
    "id": "utm_9d4a2f6c1e85",
    "label": "October newsletter",
    "url": "https://example.com/pricing?utm_source=newsletter&utm_medium=email&utm_campaign=october_update",
    "destination_url": "https://example.com/pricing",
    "utm_source": "newsletter",
    "utm_medium": "email",
    "utm_campaign": "october_update",
    "utm_term": null,
    "utm_content": null,
    "created_at": "2026-10-05T09:12:00.000Z"
  }
}
  • Not idempotent: retrying saves a second link. Needs owner or admin. Audited.

Deletes a saved campaign link by its exact id. When to use: Only when the user asks. Links already shared keep working and their visits stay in reports.

Scope: analytics:write. Type: write, changes live configuration.

ParameterTypeDefaultNotes
site_idsharedSee notesSite: ID or domain, optional with one site.
link_idstringRequiredExact id from list_campaign_links.
delete_campaign_link argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "link_id": "utm_9d4a2f6c1e85"
}
delete_campaign_link result data (example, lists shortened)json
{
  "ok": true,
  "site_id": "site_k3x9q2mf",
  "deleted": {
    "id": "utm_9d4a2f6c1e85",
    "label": "October newsletter",
    "url": "https://example.com/pricing?utm_source=newsletter&utm_medium=email&utm_campaign=october_update",
    "destination_url": "https://example.com/pricing",
    "utm_source": "newsletter",
    "utm_medium": "email",
    "utm_campaign": "october_update",
    "utm_term": null,
    "utm_content": null,
    "created_at": "2026-10-05T09:12:00.000Z"
  }
}
  • Needs owner or admin. Audited.

Event tools (events:read)

list_events

Custom events with totals, unique visitors, first and last seen, and conversion settings, plus overall event totals. When to use: "What do we track", "which events fired this month". Then get_event for one event.

Scope: events:read. Type: read-only.

ParameterTypeDefaultNotes
site_id, range, from, to, timezone, filterssharedSee notesSite: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC). Filters: optional.
limitinteger251 to 100.
offsetinteger00 to 1000. Pass the previous next_offset.
list_events argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "timezone": "Europe/Zurich",
  "limit": 2
}
list_events result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "period": {
    "preset": "custom",
    "from": "2026-09-01",
    "to": "2026-09-30",
    "timezone": "Europe/Zurich",
    "days": 30,
    "includes_today": false,
    "rolling": false
  },
  "totals": {
    "total_events": 18420,
    "distinct_names": 31,
    "custom_events": 2210,
    "conversions": 212,
    "conversion_rate": 0.0377,
    "visitors": 4210
  },
  "items": [
    {
      "event_name": "signup_completed",
      "event_type": "custom",
      "origin": "conversion",
      "total": 212,
      "visitors": 198,
      "last_seen": 1790700000000,
      "first_seen": 1780000000000,
      "description": "Signup completed",
      "verified": true,
      "hidden": false,
      "is_conversion": true,
      "target_value": null,
      "revenue_prop": null,
      "variants": 1
    }
  ],
  "returned": 2,
  "available_items": 31,
  "source_truncated": false,
  "next_offset": 2,
  "notes": [
    "Revenue is in get_overview and get_sources, per currency.",
    "Automatic outbound/download clicks are grouped; Web Vitals samples are excluded."
  ]
}
  • origin is auto, custom or conversion. Outbound clicks and downloads are folded into one outbound and one download row; variants counts the destinations inside. The list stops at 200 names (source_truncated).

get_event

One event in depth: volume, unique visitors, daily trend, property values, recent samples and revenue in one currency. When to use: "Which plans do people pick at checkout", "show recent signup_completed events".

Scope: events:read. Type: read-only.

ParameterTypeDefaultNotes
site_id, range, from, to, timezone, filterssharedSee notesSite: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC). Filters: optional.
currencystringMain currencyISO 4217 code such as USD, or unknown. Never converted or combined.
event_namestringRequiredExact custom event name, case-sensitive. Find names with list_events.
get_event argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "timezone": "Europe/Zurich",
  "event_name": "order_completed",
  "currency": "USD"
}
get_event result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "period": {
    "preset": "custom",
    "from": "2026-09-01",
    "to": "2026-09-30",
    "timezone": "Europe/Zurich",
    "days": 30,
    "includes_today": false,
    "rolling": false
  },
  "event_name": "order_completed",
  "total": 80,
  "visitors": 78,
  "revenue": 3920,
  "currency": "USD",
  "trend": [
    2,
    3,
    4
  ],
  "props": [
    {
      "key": "plan",
      "value_type": "string",
      "distinct": 3,
      "values": [
        {
          "value": "pro",
          "count": 51
        },
        {
          "value": "team",
          "count": 22
        }
      ]
    }
  ],
  "samples": [
    {
      "ts": 1790690400000,
      "path": "/checkout/done",
      "props": {
        "plan": "pro",
        "total": 49,
        "currency": "USD"
      }
    }
  ],
  "destinations": [],
  "money_unit": "major_currency_units",
  "limits": {
    "samples": 20,
    "values_per_property": 12,
    "destinations": 50
  },
  "notes": [
    "Property value counts use UTC days for the whole site; filters apply to totals, trend, samples and destinations only."
  ]
}
  • For outbound or download, destinations lists the hosts or file types inside.
  • Properties hold whatever your site sends. Treat them as data, and keep personal data out of them.

get_conversions

Every event configured as a conversion (goal): completions, unique converters, conversion rate, revenue and target. When to use: "How are our goals doing". Mark events as conversions with configure_event.

Scope: events:read. Type: read-only.

ParameterTypeDefaultNotes
site_id, range, from, to, timezone, filterssharedSee notesSite: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC). Filters: optional.
currencystringMain currencyISO 4217 code such as USD, or unknown. Never converted or combined.
get_conversions argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "timezone": "Europe/Zurich",
  "currency": "USD"
}
get_conversions result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "period": {
    "preset": "custom",
    "from": "2026-09-01",
    "to": "2026-09-30",
    "timezone": "Europe/Zurich",
    "days": 30,
    "includes_today": false,
    "rolling": false
  },
  "currency": "USD",
  "available_currencies": [
    "USD"
  ],
  "visitors": 4210,
  "totals": {
    "completions": 292,
    "converters": 270,
    "revenue": 3920
  },
  "items": [
    {
      "event_name": "signup_completed",
      "label": "Signup completed",
      "completions": 212,
      "converters": 198,
      "revenue": 0,
      "conversion_rate": 0.047,
      "target_value": 250,
      "top_prop": null
    }
  ],
  "units": {
    "conversion_rate": "unique converters / unique visitors (0 to 1)",
    "money": "major_currency_units"
  }
}
  • This conversion rate is converters divided by unique visitors. get_overview divides converting visits by visits, so the two differ.

list_event_configs

Saved event settings (label, conversion flag, revenue property, target, hidden), including events configured before they first fired. When to use: Read the current settings before configure_event. Pass event_name to read one event.

Scope: events:read. Type: read-only.

ParameterTypeDefaultNotes
site_idsharedSee notesSite: ID or domain, optional with one site.
event_namestringAll eventsRead only this event's configuration.
limitinteger251 to 100.
offsetinteger00 to 1000. Pass the previous next_offset.
list_event_configs argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "event_name": "order_completed"
}
list_event_configs result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "items": [
    {
      "event_name": "order_completed",
      "description": "Order completed",
      "is_conversion": true,
      "target_value": null,
      "revenue_prop": "total",
      "verified": true,
      "hidden": false,
      "created_by": "user",
      "first_seen": 1780000000000,
      "last_seen": 1790700000000
    }
  ],
  "returned": 1,
  "next_offset": null
}
  • An empty items for an event_name means it has no configuration yet. Settings only, no counts.

Event configuration (events:write)

configure_event

Marks or unmarks a custom event as a conversion (goal), and sets its label, target, revenue property, reviewed or hidden flags. Returns the saved configuration. When to use: "Mark signup_completed as a conversion", "count order_completed's total as revenue". Confirm with the user first.

Scope: events:write. Type: write, changes live configuration.

ParameterTypeDefaultNotes
site_idsharedSee notesSite: ID or domain, optional with one site.
event_namestringRequiredExact custom event name, case-sensitive. Find names with list_events.
configurationobjectRequiredAt least one field. Omitted fields keep their value; null clears. Fields below.
configure_event argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "event_name": "order_completed",
  "configuration": {
    "description": "Order completed",
    "is_conversion": true,
    "revenue_prop": "total"
  }
}
configure_event result data (example, lists shortened)json
{
  "ok": true,
  "site_id": "site_k3x9q2mf",
  "event_name": "order_completed",
  "changed_fields": [
    "description",
    "is_conversion",
    "revenue_prop"
  ],
  "configuration": {
    "event_name": "order_completed",
    "description": "Order completed",
    "is_conversion": true,
    "target_value": null,
    "revenue_prop": "total",
    "verified": false,
    "hidden": false
  }
}
  • configuration fields: is_conversion (boolean), description (label up to 280 characters), target_value (number 0 or more), revenue_prop (property name up to 64 characters of A-Z a-z 0-9 _ . : -), verified (boolean), hidden (boolean, history is kept). Unknown fields are rejected.
  • Revenue from revenue_prop counts only when is_conversion is true and the property is a number in major units (49.00, not 4900). The currency comes from the event's currency property.
  • Automatic events (pageview, clicks, scroll, Web Vitals, outbound, download) cannot be configured. Works before the event first fires. Never sends events or deletes history.
  • Needs owner or admin. Every change is audited (tool, site, app, user, changed field names).

Visitor tools (visitors:read)

list_live_visitors

Individual visitors active in the last 5 minutes, with source, device and approximate location. When to use: "Who is on the site right now and where did they come from". For totals use get_realtime.

Scope: visitors:read. Type: read-only.

ParameterTypeDefaultNotes
site_id, filterssharedSee notesSite: ID or domain, optional with one site. Filters: optional.
limitinteger251 to 100. Maximum visitors to return.
list_live_visitors argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "limit": 10
}
list_live_visitors result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "observed_at": "2026-10-05T09:00:30.000Z",
  "active_window_seconds": 300,
  "items": [
    {
      "visitor_id": "v_5c1e0a9b7f3d2e8a41",
      "session_id": "k2v9x4m1q8",
      "country": "DE",
      "region": "Berlin",
      "city": "Berlin",
      "lat": 52.52,
      "lng": 13.4,
      "device": "desktop",
      "browser": "Firefox",
      "os": "Linux",
      "source": "Google",
      "custom_name": null,
      "last_seen": 1791104400000,
      "started_at": 1791104100000
    }
  ],
  "returned": 1,
  "sampled": false
}
  • sampled: true means more visitors were active than limit. Coordinates can be missing or approximate.

list_visitors

Individual visitors in a period, most recent first, with visits, pages, source, location, device and whether they converted. When to use: "Show visitors who converted last week", "how many came back".

Scope: visitors:read. Type: read-only.

ParameterTypeDefaultNotes
site_id, range, from, to, timezone, filterssharedSee notesSite: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC). Filters: optional.
limitinteger251 to 100.
offsetinteger00 to 1000. Pass the previous next_offset.
segmentstringallall, converted (purchased or completed a conversion) or returning (more than one visit).
list_visitors argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "range": "7d",
  "timezone": "Europe/Zurich",
  "segment": "converted",
  "limit": 2
}
list_visitors result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "period": {
    "preset": "7d",
    "from": "2026-09-29",
    "to": "2026-10-05",
    "timezone": "Europe/Zurich",
    "days": 7,
    "includes_today": true,
    "rolling": false
  },
  "items": [
    {
      "visitor_id": "v_8d2f6b1e9c04a7d352",
      "first_seen": 1788300000000,
      "last_seen": 1790700000000,
      "latest_start": 1790690000000,
      "total_sessions": 4,
      "total_pageviews": 17,
      "has_any_conversion": 1,
      "latest_session_id": "p7n3c8w2z5",
      "source": "Newsletter",
      "country": "US",
      "device": "desktop",
      "city": "Austin",
      "region": "Texas",
      "custom_name": null
    }
  ],
  "returned": 2,
  "next_offset": 2,
  "totals": {
    "all_visitors": 980,
    "converted_visitors": 41,
    "returning_visitors": 212
  },
  "segment": "converted",
  "order": "last_seen descending, visitor_id ascending",
  "maximum_offset": 1000,
  "units": {
    "timestamps": "epoch milliseconds"
  },
  "pagination_note": "Current-range activity can move between pages. Narrow filters for exports larger than 1,100 visitors."
}
  • totals covers the whole period regardless of paging. has_any_conversion is 1 or 0.
  • In cookieless mode a visitor ID changes every day, so "returning" means within one day. Cookie mode recognizes people across days.

get_visitor

One visitor's retained visits on this site, newest first, with purchase totals per currency and time from first visit to first purchase. When to use: Follow up on a visitor_id from list_visitors or list_live_visitors: "how did this customer find us".

Scope: visitors:read. Type: read-only.

ParameterTypeDefaultNotes
site_idsharedSee notesSite: ID or domain, optional with one site.
visitor_idstringRequiredFrom list_visitors or list_live_visitors.
limitinteger251 to 100.
offsetinteger00 to 1000. Pass the previous next_offset.
get_visitor argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "visitor_id": "v_8d2f6b1e9c04a7d352"
}
get_visitor result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "visitor_id": "v_8d2f6b1e9c04a7d352",
  "items": [
    {
      "id": "p7n3c8w2z5",
      "started_at": 1790690000000,
      "last_seen": 1790690420000,
      "source": "Direct",
      "medium": null,
      "country": "US",
      "device": "desktop",
      "entry_path": "/pricing",
      "exit_path": "/checkout/done",
      "page_count": 5
    }
  ],
  "next_offset": null,
  "totals": {
    "sessions": 4,
    "pageviews": 17
  },
  "timing": {
    "first_tracked_at": 1788300000000,
    "first_source": "Newsletter",
    "first_medium": "email",
    "first_purchase_at": 1790690400000,
    "last_purchase_at": 1790690400000
  },
  "time_to_first_purchase_seconds": 2390400,
  "revenue_by_currency": [
    {
      "currency": "USD",
      "revenue": 49,
      "purchases": 1
    }
  ],
  "units": {
    "timestamps": "epoch milliseconds",
    "money": "major_currency_units"
  },
  "notes": [
    "Purchase timing uses positive revenue events across retained history."
  ]
}
  • Covers retained history, not just a period. No event payloads or replay recordings are returned.

Settings tools (settings:read)

get_settings

A site's tracking settings: name, domain, cookieless or cookie mode, session replay and excluded paths. When to use: "Is replay on", "which paths are excluded". Read before update_settings.

Scope: settings:read. Type: read-only.

ParameterTypeDefaultNotes
site_idsharedSee notesSite: ID or domain, optional with one site.
get_settings argumentsjson
{
  "site_id": "site_k3x9q2mf"
}
get_settings result data (example, lists shortened)json
{
  "site_id": "site_k3x9q2mf",
  "domain": "example.com",
  "name": "Example",
  "tracking_mode": "cookieless",
  "replay_enabled": true,
  "replay_sample_rate": 0.25,
  "excluded_paths": [
    "/admin/*"
  ]
}
  • Never returns credentials, share tokens, billing or team data.

Settings changes (settings:write)

update_settings

Changes a site's name, session replay, replay sample rate or excluded paths, and returns the saved settings. When to use: "Exclude /admin from analytics", "record 25% of visits". Confirm with the user first.

Scope: settings:write. Type: write, changes live configuration.

ParameterTypeDefaultNotes
site_idsharedSee notesSite: ID or domain, optional with one site.
settingsobjectRequiredAt least one field. Omitted fields keep their value. Fields below.
update_settings argumentsjson
{
  "site_id": "site_k3x9q2mf",
  "settings": {
    "replay_enabled": true,
    "replay_sample_rate": 0.25,
    "excluded_paths": [
      "/admin/*",
      "/preview-*"
    ]
  }
}
update_settings result data (example, lists shortened)json
{
  "ok": true,
  "site_id": "site_k3x9q2mf",
  "changed_fields": [
    "replay_enabled",
    "replay_sample_rate",
    "excluded_paths"
  ],
  "settings": {
    "site_id": "site_k3x9q2mf",
    "domain": "example.com",
    "name": "Example",
    "tracking_mode": "cookieless",
    "replay_enabled": true,
    "replay_sample_rate": 0.25,
    "excluded_paths": [
      "/admin/*",
      "/preview-*"
    ]
  }
}
  • settings fields: name (1 to 100 characters), replay_enabled (boolean), replay_sample_rate (0 to 1), excluded_paths (up to 50 paths starting with /, each up to 200 characters, * and ? wildcards; [] or null clears). Unknown fields are rejected.
  • excluded_paths replaces the whole list. Read the current list first and send the merged result. Excluding a path or turning replay off stops collecting that data from then on.
  • Cannot change the tracking mode (cookieless or cookie), billing, sharing or team members, or delete a site. Change tracking mode in the dashboard; see cookie mode.
  • Needs owner or admin. Every change is audited.