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.
On this page
- Tools at a glance
- Conventions
- Choosing a site
- Dates and time zones
- Comparison periods
- Filters
- Currency and money
- Units
- Pagination and limits
- Freshness
- Result format
- Connection tools
- list_sites
- Analytics tools (analytics:read)
- get_overview
- get_timeseries
- get_breakdown
- get_sources
- get_realtime
- get_ai_referrals
- get_ai_crawlers
- get_outbound_links
- get_web_vitals
- get_journeys
- list_funnels
- get_funnel_report
- list_annotations
- list_campaign_links
- Funnels, annotations and campaign links (analytics:write)
- create_funnel
- update_funnel
- delete_funnel
- create_annotation
- delete_annotation
- create_campaign_link
- delete_campaign_link
- Event tools (events:read)
- list_events
- get_event
- get_conversions
- list_event_configs
- Event configuration (events:write)
- configure_event
- Visitor tools (visitors:read)
- list_live_visitors
- list_visitors
- get_visitor
- Settings tools (settings:read)
- get_settings
- Settings changes (settings:write)
- 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
| Tool | Scope | What it returns |
|---|---|---|
list_sites | none | Lists the sites this connection may read and the permissions it was granted. |
get_overview | analytics:read | Headline KPIs for a period, each compared with the previous period of equal length. |
get_timeseries | analytics:read | One point per bucket for the metrics you ask for: daily, hourly or every 15 minutes. |
get_breakdown | analytics:read | Top values of one dimension with counts and share of the total. |
get_sources | analytics:read | Acquisition sources (Google, ChatGPT, Direct, newsletters) with visits, conversions, purchases, revenue and time to purchase. |
get_realtime | analytics:read | Visitors active in the last 5 minutes, with top countries, pages and devices. |
get_ai_referrals | analytics:read | People who arrived from AI assistants (ChatGPT, Perplexity, Claude, Gemini, Copilot), with share, split by assistant, landing pages and a daily trend. |
get_ai_crawlers | analytics:read | Requests from AI and search crawlers (GPTBot, ClaudeBot, PerplexityBot) by crawler, provider, category and path. |
get_outbound_links | analytics:read | Clicks on links to other domains, by host, and file downloads, by file type. |
get_web_vitals | analytics:read | 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. |
get_journeys | analytics:read | Landing and exit pages, and the 12 most common page sequences up to 5 steps. |
list_funnels | analytics:read | Saved funnels with their ordered steps, exclusions, conversion window, order and breakdown. |
get_funnel_report | analytics:read | Evaluates a saved funnel: visitors per step, drop-off, step and overall conversion, time to convert and a daily trend. |
create_funnel | analytics:write | Saves a new funnel of 2 to 10 page or event steps, with the same validation as the dashboard. |
update_funnel | analytics:write | Changes a saved funnel by its exact id. Omitted fields keep their value; steps, when given, replace all steps. |
delete_funnel | analytics:write | Permanently deletes a saved funnel by its exact id. Collected data is not affected. |
list_annotations | analytics:read | Dated chart notes, such as "Launched on Product Hunt", in a period. |
create_annotation | analytics:write | Adds a dated note to the site's charts, such as a launch, campaign or outage. |
delete_annotation | analytics:write | Permanently deletes a chart annotation by its exact id. |
list_campaign_links | analytics:read | Saved campaign (UTM) links, newest first, with the full tagged URL. |
create_campaign_link | analytics:write | Saves a campaign (UTM) link and returns the tagged URL to share. |
delete_campaign_link | analytics:write | Deletes a saved campaign link by its exact id. |
list_events | events:read | Custom events with totals, unique visitors, first and last seen, and conversion settings, plus overall event totals. |
get_event | events:read | One event in depth: volume, unique visitors, daily trend, property values, recent samples and revenue in one currency. |
get_conversions | events:read | Every event configured as a conversion (goal): completions, unique converters, conversion rate, revenue and target. |
list_event_configs | events:read | Saved event settings (label, conversion flag, revenue property, target, hidden), including events configured before they first fired. |
configure_event | events:write | 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. |
list_live_visitors | visitors:read | Individual visitors active in the last 5 minutes, with source, device and approximate location. |
list_visitors | visitors:read | Individual visitors in a period, most recent first, with visits, pages, source, location, device and whether they converted. |
get_visitor | visitors:read | One visitor's retained visits on this site, newest first, with purchase totals per currency and time from first visit to first purchase. |
get_settings | settings:read | A site's tracking settings: name, domain, cookieless or cookie mode, session replay and excluded paths. |
update_settings | settings:write | Changes 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
| range | Covers |
|---|---|
today | Today so far, in timezone. |
yesterday | Yesterday, midnight to midnight in timezone. |
24h | The rolling 24 hours ending now. |
7d, 30d, 90d | That many calendar days ending today, today included. |
12m | The last 365 days, today included. |
custom | from to to, both YYYY-MM-DD and inclusive. to defaults to today. At most 366 days. |
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.
{
"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.
| Dimension | Example values |
|---|---|
country | US, DE (ISO 3166-1 alpha-2) |
region, city | California, Zurich |
device | desktop, mobile, tablet |
browser, os | Chrome, Safari, macOS, iOS |
source | Google, Direct, ChatGPT, as returned by get_sources |
medium, utm_source, utm_medium, utm_campaign | email, newsletter, cpc, spring_launch |
entry_path, exit_path | /pricing |
referrer | news.ycombinator.com |
language, timezone | en-US, Europe/Berlin |
event | signup_completed: visits that fired this custom event |
(none) matches an empty value, for example visits with no campaign.{
"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
| Field | Unit |
|---|---|
change_pct | Percent change vs compare_period (8.8 = +8.8%). null when the previous value was 0. |
bounce_rate, conversion_rate, share, conv_from_*, rate | Fraction from 0 to 1 |
*_seconds | Seconds |
*_ms | Milliseconds |
ts, first_seen, last_seen, started_at, *_at (numbers) | Epoch milliseconds |
start, observed_at | ISO 8601 string, UTC |
date | YYYY-MM-DD in the period's time zone |
Web Vitals p75, p95 | Milliseconds, except CLS (unitless) |
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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
limit | integer | 25 | 1 to 100. |
offset | integer | 0 | 0 to 1000. Pass the previous next_offset. |
{}{
"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.
roleisowner,adminormember. Write tools needowneroradmin.
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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
site_id, range, from, to, timezone, filters | shared | See notes | Site: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC). Filters: optional. |
currency | string | Main currency | ISO 4217 code such as USD, or unknown. Never converted or combined. |
{
"site_id": "site_k3x9q2mf",
"from": "2026-09-01",
"to": "2026-09-30",
"timezone": "Europe/Zurich",
"currency": "USD"
}{
"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_periodends the day beforeperiodstarts and has the same length.visitorscounts 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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
site_id, range, from, to, timezone, filters | shared | See notes | Site: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC). Filters: optional. |
currency | string | Main currency | ISO 4217 code such as USD, or unknown. Never converted or combined. |
metrics | string[] | ["visitors"] | 1 to 6 of visitors, visits, pageviews, bounce_rate, avg_visit_duration_seconds, revenue. |
interval | string | hour up to 2 days, else day | 15m, hour or day. 15m and hour support only visitors and revenue, up to 744 buckets. |
{
"site_id": "site_k3x9q2mf",
"range": "yesterday",
"timezone": "Europe/Zurich",
"metrics": [
"visitors",
"revenue"
],
"interval": "15m",
"currency": "USD"
}{
"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-DDintimezone). Sub-day points carrystart, 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_overviewfor 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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
site_id, range, from, to, timezone, filters | shared | See notes | Site: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC). Filters: optional. |
dimension | string | Required | page, entry_page, exit_page, referrer, medium, utm_source, utm_medium, utm_campaign, country, region, city, device, browser, os or language. |
metric | string | visitors | visitors (unique people), visits (sessions) or pageviews. |
limit | integer | 10 | 1 to 100. |
{
"site_id": "site_k3x9q2mf",
"from": "2026-09-01",
"to": "2026-09-30",
"timezone": "Europe/Zurich",
"dimension": "country",
"limit": 3
}{
"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%."
]
}pagereturns at most 20 rows; other dimensions up to 100.regionrows addcountry,cityrows addregionandcountry.- With filters,
pagecounts 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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
site_id, range, from, to, timezone, filters | shared | See notes | Site: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC). Filters: optional. |
currency | string | Main currency | ISO 4217 code such as USD, or unknown. Never converted or combined. |
sort | string | visitors | visitors, visits, conversions or revenue. |
limit | integer | 10 | 1 to 100. |
offset | integer | 0 | 0 to 1000. Pass the previous next_offset. |
{
"site_id": "site_k3x9q2mf",
"from": "2026-09-01",
"to": "2026-09-30",
"timezone": "Europe/Zurich",
"currency": "USD",
"sort": "revenue",
"limit": 2
}{
"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_revenueand appears as the sourceUnattributed.
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.
{
"site_id": "site_k3x9q2mf"
}{
"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.
{
"site_id": "site_k3x9q2mf",
"from": "2026-09-01",
"to": "2026-09-30",
"timezone": "Europe/Zurich"
}{
"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.
{
"site_id": "site_k3x9q2mf",
"range": "30d"
}{
"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.categoryisassistant,searchortraining.
get_outbound_links
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.
{
"site_id": "site_k3x9q2mf",
"from": "2026-09-01",
"to": "2026-09-30",
"timezone": "Europe/Zurich"
}{
"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.
{
"site_id": "site_k3x9q2mf",
"from": "2026-09-01",
"to": "2026-09-30",
"timezone": "Europe/Zurich",
"filters": {
"device": [
"mobile"
]
}
}{
"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: trueif there were more). Metrics with no samples returnnull, 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.
{
"site_id": "site_k3x9q2mf",
"from": "2026-09-01",
"to": "2026-09-30",
"timezone": "Europe/Zurich",
"depth": 3
}{
"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: truemeans 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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
site_id | shared | See notes | Site: ID or domain, optional with one site. |
limit | integer | 25 | 1 to 100. |
offset | integer | 0 | 0 to 1000. Pass the previous next_offset. |
{
"site_id": "site_k3x9q2mf"
}{
"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.
{
"site_id": "site_k3x9q2mf",
"from": "2026-09-01",
"to": "2026-09-30",
"timezone": "Europe/Zurich",
"funnel_id": "fnl_3b8e51c2a9d0"
}{
"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 hasvisitors:read.truncated: truemeans 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.
{
"site_id": "site_k3x9q2mf",
"from": "2026-09-01",
"to": "2026-09-30",
"timezone": "Europe/Zurich"
}{
"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"
}
]
}list_campaign_links
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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
site_id | shared | See notes | Site: ID or domain, optional with one site. |
limit | integer | 25 | 1 to 100. |
offset | integer | 0 | 0 to 1000. Pass the previous next_offset. |
{
"site_id": "site_k3x9q2mf"
}{
"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
}Funnels, annotations and campaign links (analytics:write)
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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
site_id | shared | See notes | Site: ID or domain, optional with one site. |
name | string | Required | Up to 80 characters. |
steps | object[] | Required | 2 to 10 ordered steps. See the step fields below. |
exclusions | object[] | None | Up to 5 actions that remove a visitor when done between two steps. |
conversion_window | object | 14 days | { value, unit }: value 1 to 365, unit minute, hour, day or week. Time from first to last step. |
order | string | sequential | sequential (in order, other activity allowed), strict (no other funnel step in between) or any. |
breakdown | string or null | None | Split 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. |
{
"site_id": "site_k3x9q2mf",
"name": "Signup",
"steps": [
{
"type": "page",
"value": "/pricing"
},
{
"type": "event",
"value": "signup_completed",
"label": "Signup"
}
],
"conversion_window": {
"value": 14,
"unit": "day"
}
}{
"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(pageorevent),value(a path such as/pricing, or a custom event name, up to 200 characters),match(exactdefault,contains,prefix,regex), optionalalternatives(up to 5 more paths or names that also count),conditions(up to 5 property checks:key,opofeq,neq,contains,gt,lt,set,unset, andvalue) andlabel(up to 80 characters). - Each exclusion has the same target fields plus
from_stepandto_step(1-based, default the whole funnel). - Not idempotent: retrying a create saves a second funnel. Needs
owneroradmin. 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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
site_id | shared | See notes | Site: ID or domain, optional with one site. |
funnel_id | string | Required | Exact id from list_funnels. |
name | string | Unchanged | Up to 80 characters. |
steps | object[] | Unchanged | 2 to 10 ordered steps. See the step fields below. |
exclusions | object[] | None | Up to 5 actions that remove a visitor when done between two steps. |
conversion_window | object | 14 days | { value, unit }: value 1 to 365, unit minute, hour, day or week. Time from first to last step. |
order | string | sequential | sequential (in order, other activity allowed), strict (no other funnel step in between) or any. |
breakdown | string or null | None | Split 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. |
{
"site_id": "site_k3x9q2mf",
"funnel_id": "fnl_3b8e51c2a9d0",
"order": "strict",
"conversion_window": {
"value": 7,
"unit": "day"
}
}{
"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
owneroradmin. 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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
site_id | shared | See notes | Site: ID or domain, optional with one site. |
funnel_id | string | Required | Exact id from list_funnels. |
{
"site_id": "site_k3x9q2mf",
"funnel_id": "fnl_3b8e51c2a9d0"
}{
"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
owneroradmin. 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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
site_id | shared | See notes | Site: ID or domain, optional with one site. |
date | string | Required | YYYY-MM-DD. |
label | string | Required | 1 to 120 characters. |
{
"site_id": "site_k3x9q2mf",
"date": "2026-10-05",
"label": "October newsletter sent"
}{
"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
owneroradmin. 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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
site_id | shared | See notes | Site: ID or domain, optional with one site. |
annotation_id | string | Required | Exact id from list_annotations. |
{
"site_id": "site_k3x9q2mf",
"annotation_id": "ann_7f1b3c9e2a40"
}{
"ok": true,
"site_id": "site_k3x9q2mf",
"deleted": {
"id": "ann_7f1b3c9e2a40",
"date": "2026-10-05",
"label": "October newsletter sent"
}
}- Needs
owneroradmin. Audited.
create_campaign_link
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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
site_id | shared | See notes | Site: ID or domain, optional with one site. |
destination_url | string | Required | Full landing page URL with https://, up to 2,000 characters. Existing query parameters are kept. |
utm_source | string | Required | Up to 80 characters, such as newsletter. |
utm_medium | string | Required | Up to 80 characters, such as email. |
utm_campaign | string | Required | Up to 120 characters, such as october_update. |
utm_term | string | None | Optional keyword, up to 80 characters. |
utm_content | string | None | Optional variant, up to 120 characters. |
label | string | None | Optional name to find it later, up to 120 characters. |
{
"site_id": "site_k3x9q2mf",
"destination_url": "https://example.com/pricing",
"utm_source": "newsletter",
"utm_medium": "email",
"utm_campaign": "october_update",
"label": "October newsletter"
}{
"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
owneroradmin. Audited.
delete_campaign_link
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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
site_id | shared | See notes | Site: ID or domain, optional with one site. |
link_id | string | Required | Exact id from list_campaign_links. |
{
"site_id": "site_k3x9q2mf",
"link_id": "utm_9d4a2f6c1e85"
}{
"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
owneroradmin. 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.
{
"site_id": "site_k3x9q2mf",
"from": "2026-09-01",
"to": "2026-09-30",
"timezone": "Europe/Zurich",
"limit": 2
}{
"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."
]
}originisauto,customorconversion. Outbound clicks and downloads are folded into oneoutboundand onedownloadrow;variantscounts 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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
site_id, range, from, to, timezone, filters | shared | See notes | Site: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC). Filters: optional. |
currency | string | Main currency | ISO 4217 code such as USD, or unknown. Never converted or combined. |
event_name | string | Required | Exact custom event name, case-sensitive. Find names with list_events. |
{
"site_id": "site_k3x9q2mf",
"from": "2026-09-01",
"to": "2026-09-30",
"timezone": "Europe/Zurich",
"event_name": "order_completed",
"currency": "USD"
}{
"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
outboundordownload,destinationslists 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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
site_id, range, from, to, timezone, filters | shared | See notes | Site: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC). Filters: optional. |
currency | string | Main currency | ISO 4217 code such as USD, or unknown. Never converted or combined. |
{
"site_id": "site_k3x9q2mf",
"from": "2026-09-01",
"to": "2026-09-30",
"timezone": "Europe/Zurich",
"currency": "USD"
}{
"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_overviewdivides 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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
site_id | shared | See notes | Site: ID or domain, optional with one site. |
event_name | string | All events | Read only this event's configuration. |
limit | integer | 25 | 1 to 100. |
offset | integer | 0 | 0 to 1000. Pass the previous next_offset. |
{
"site_id": "site_k3x9q2mf",
"event_name": "order_completed"
}{
"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
itemsfor anevent_namemeans 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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
site_id | shared | See notes | Site: ID or domain, optional with one site. |
event_name | string | Required | Exact custom event name, case-sensitive. Find names with list_events. |
configuration | object | Required | At least one field. Omitted fields keep their value; null clears. Fields below. |
{
"site_id": "site_k3x9q2mf",
"event_name": "order_completed",
"configuration": {
"description": "Order completed",
"is_conversion": true,
"revenue_prop": "total"
}
}{
"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
}
}configurationfields:is_conversion(boolean),description(label up to 280 characters),target_value(number 0 or more),revenue_prop(property name up to 64 characters ofA-Z a-z 0-9 _ . : -),verified(boolean),hidden(boolean, history is kept). Unknown fields are rejected.- Revenue from
revenue_propcounts only whenis_conversionistrueand the property is a number in major units (49.00, not4900). The currency comes from the event'scurrencyproperty. - 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
owneroradmin. 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.
{
"site_id": "site_k3x9q2mf",
"limit": 10
}{
"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: truemeans more visitors were active thanlimit. 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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
site_id, range, from, to, timezone, filters | shared | See notes | Site: ID or domain, optional with one site. Period: range preset (default 30d) or from/to, plus timezone (default UTC). Filters: optional. |
limit | integer | 25 | 1 to 100. |
offset | integer | 0 | 0 to 1000. Pass the previous next_offset. |
segment | string | all | all, converted (purchased or completed a conversion) or returning (more than one visit). |
{
"site_id": "site_k3x9q2mf",
"range": "7d",
"timezone": "Europe/Zurich",
"segment": "converted",
"limit": 2
}{
"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."
}totalscovers the whole period regardless of paging.has_any_conversionis1or0.- 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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
site_id | shared | See notes | Site: ID or domain, optional with one site. |
visitor_id | string | Required | From list_visitors or list_live_visitors. |
limit | integer | 25 | 1 to 100. |
offset | integer | 0 | 0 to 1000. Pass the previous next_offset. |
{
"site_id": "site_k3x9q2mf",
"visitor_id": "v_8d2f6b1e9c04a7d352"
}{
"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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
site_id | shared | See notes | Site: ID or domain, optional with one site. |
{
"site_id": "site_k3x9q2mf"
}{
"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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
site_id | shared | See notes | Site: ID or domain, optional with one site. |
settings | object | Required | At least one field. Omitted fields keep their value. Fields below. |
{
"site_id": "site_k3x9q2mf",
"settings": {
"replay_enabled": true,
"replay_sample_rate": 0.25,
"excluded_paths": [
"/admin/*",
"/preview-*"
]
}
}{
"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-*"
]
}
}settingsfields: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;[]ornullclears). Unknown fields are rejected.excluded_pathsreplaces 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
owneroradmin. Every change is audited.