# 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.

Section: AI assistants (MCP). Canonical page: https://mrkr.app/docs/integrations/mcp-tools. Last updated: 2026-10-05.

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`](#list-sites) | none | Lists the sites this connection may read and the permissions it was granted. |
| [`get_overview`](#get-overview) | `analytics:read` | Headline KPIs for a period, each compared with the previous period of equal length. |
| [`get_timeseries`](#get-timeseries) | `analytics:read` | One point per bucket for the metrics you ask for: daily, hourly or every 15 minutes. |
| [`get_breakdown`](#get-breakdown) | `analytics:read` | Top values of one dimension with counts and share of the total. |
| [`get_sources`](#get-sources) | `analytics:read` | Acquisition sources (Google, ChatGPT, Direct, newsletters) with visits, conversions, purchases, revenue and time to purchase. |
| [`get_realtime`](#get-realtime) | `analytics:read` | Visitors active in the last 5 minutes, with top countries, pages and devices. |
| [`get_ai_referrals`](#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`](#get-ai-crawlers) | `analytics:read` | Requests from AI and search crawlers (GPTBot, ClaudeBot, PerplexityBot) by crawler, provider, category and path. |
| [`get_outbound_links`](#get-outbound-links) | `analytics:read` | Clicks on links to other domains, by host, and file downloads, by file type. |
| [`get_web_vitals`](#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`](#get-journeys) | `analytics:read` | Landing and exit pages, and the 12 most common page sequences up to 5 steps. |
| [`list_funnels`](#list-funnels) | `analytics:read` | Saved funnels with their ordered steps, exclusions, conversion window, order and breakdown. |
| [`get_funnel_report`](#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`](#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`](#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`](#delete-funnel) | `analytics:write` | Permanently deletes a saved funnel by its exact id. Collected data is not affected. |
| [`list_annotations`](#list-annotations) | `analytics:read` | Dated chart notes, such as "Launched on Product Hunt", in a period. |
| [`create_annotation`](#create-annotation) | `analytics:write` | Adds a dated note to the site's charts, such as a launch, campaign or outage. |
| [`delete_annotation`](#delete-annotation) | `analytics:write` | Permanently deletes a chart annotation by its exact id. |
| [`list_campaign_links`](#list-campaign-links) | `analytics:read` | Saved campaign (UTM) links, newest first, with the full tagged URL. |
| [`create_campaign_link`](#create-campaign-link) | `analytics:write` | Saves a campaign (UTM) link and returns the tagged URL to share. |
| [`delete_campaign_link`](#delete-campaign-link) | `analytics:write` | Deletes a saved campaign link by its exact id. |
| [`list_events`](#list-events) | `events:read` | Custom events with totals, unique visitors, first and last seen, and conversion settings, plus overall event totals. |
| [`get_event`](#get-event) | `events:read` | One event in depth: volume, unique visitors, daily trend, property values, recent samples and revenue in one currency. |
| [`get_conversions`](#get-conversions) | `events:read` | Every event configured as a conversion (goal): completions, unique converters, conversion rate, revenue and target. |
| [`list_event_configs`](#list-event-configs) | `events:read` | Saved event settings (label, conversion flag, revenue property, target, hidden), including events configured before they first fired. |
| [`configure_event`](#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`](#list-live-visitors) | `visitors:read` | Individual visitors active in the last 5 minutes, with source, device and approximate location. |
| [`list_visitors`](#list-visitors) | `visitors:read` | Individual visitors in a period, most recent first, with visits, pages, source, location, device and whether they converted. |
| [`get_visitor`](#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`](#get-settings) | `settings:read` | A site's tracking settings: name, domain, cookieless or cookie mode, session replay and excluded paths. |
| [`update_settings`](#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. |

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 Zurich:

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

Mobile visitors from Google or Bing in the US or Canada:

```json
{
  "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) |

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](https://mrkr.app/docs/integrations/mcp-troubleshooting#errors-and-fixes).

## 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`. |

list_sites arguments:

```json
{}
```

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.

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id`, `range`, `from`, `to`, `timezone`, `filters` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. [Period](#dates-and-time-zones): `range` preset (default `30d`) or `from`/`to`, plus `timezone` (default `UTC`). [Filters](#filters): optional. |
| `currency` | string | Main currency | ISO 4217 code such as `USD`, or `unknown`. Never converted or combined. |

get_overview arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id`, `range`, `from`, `to`, `timezone`, `filters` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. [Period](#dates-and-time-zones): `range` preset (default `30d`) or `from`/`to`, plus `timezone` (default `UTC`). [Filters](#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. |

get_timeseries arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id`, `range`, `from`, `to`, `timezone`, `filters` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. [Period](#dates-and-time-zones): `range` preset (default `30d`) or `from`/`to`, plus `timezone` (default `UTC`). [Filters](#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. |

get_breakdown arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id`, `range`, `from`, `to`, `timezone`, `filters` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. [Period](#dates-and-time-zones): `range` preset (default `30d`) or `from`/`to`, plus `timezone` (default `UTC`). [Filters](#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`. |

get_sources arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id`, `filters` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. [Filters](#filters): optional. |

get_realtime arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id`, `range`, `from`, `to`, `timezone`, `filters` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. [Period](#dates-and-time-zones): `range` preset (default `30d`) or `from`/`to`, plus `timezone` (default `UTC`). [Filters](#filters): optional. |

get_ai_referrals arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id`, `range`, `from`, `to`, `timezone` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. [Period](#dates-and-time-zones): `range` preset (default `30d`) or `from`/`to`, plus `timezone` (default `UTC`). `timezone`: Accepted but ignored. Days are always UTC. |

get_ai_crawlers arguments:

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

### `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.

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id`, `range`, `from`, `to`, `timezone`, `filters` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. [Period](#dates-and-time-zones): `range` preset (default `30d`) or `from`/`to`, plus `timezone` (default `UTC`). [Filters](#filters): optional. |

get_outbound_links arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id`, `range`, `from`, `to`, `timezone`, `filters` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. [Period](#dates-and-time-zones): `range` preset (default `30d`) or `from`/`to`, plus `timezone` (default `UTC`). [Filters](#filters): optional. |

get_web_vitals arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id`, `range`, `from`, `to`, `timezone`, `filters` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. [Period](#dates-and-time-zones): `range` preset (default `30d`) or `from`/`to`, plus `timezone` (default `UTC`). [Filters](#filters): optional. |
| `depth` | integer | 3 | Pages per path, 1 to 5. |

get_journeys arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id` | shared | See notes | [Site](#choosing-a-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`. |

list_funnels arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id`, `range`, `from`, `to`, `timezone`, `filters` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. [Period](#dates-and-time-zones): `range` preset (default `30d`) or `from`/`to`, plus `timezone` (default `UTC`). [Filters](#filters): optional. |
| `funnel_id` | string | Required | An `id` from `list_funnels` or `create_funnel`. |

get_funnel_report arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id`, `range`, `from`, `to`, `timezone` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. [Period](#dates-and-time-zones): `range` preset (default `30d`) or `from`/`to`, plus `timezone` (default `UTC`). |

list_annotations arguments:

```json
{
  "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"
    }
  ]
}
```

### `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](#choosing-a-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`. |

list_campaign_links arguments:

```json
{
  "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
}
```

## Funnels, annotations and campaign links (analytics:write)

> **Note:** These tools need `analytics:write`, shown on the consent screen as **Edit reports** (off by default, owners and admins only). A connection made without it keeps read access; reconnect and tick Edit reports to add it. They change saved reports, never collected data.

### `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](#choosing-a-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. |

create_funnel arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id` | shared | See notes | [Site](#choosing-a-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. |

update_funnel arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. |
| `funnel_id` | string | Required | Exact id from `list_funnels`. |

delete_funnel arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. |
| `date` | string | Required | `YYYY-MM-DD`. |
| `label` | string | Required | 1 to 120 characters. |

create_annotation arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. |
| `annotation_id` | string | Required | Exact id from `list_annotations`. |

delete_annotation arguments:

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

### `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](#choosing-a-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. |

create_campaign_link arguments:

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

### `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](#choosing-a-site): ID or domain, optional with one site. |
| `link_id` | string | Required | Exact id from `list_campaign_links`. |

delete_campaign_link arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id`, `range`, `from`, `to`, `timezone`, `filters` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. [Period](#dates-and-time-zones): `range` preset (default `30d`) or `from`/`to`, plus `timezone` (default `UTC`). [Filters](#filters): optional. |
| `limit` | integer | 25 | 1 to 100. |
| `offset` | integer | 0 | 0 to 1000. Pass the previous `next_offset`. |

list_events arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id`, `range`, `from`, `to`, `timezone`, `filters` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. [Period](#dates-and-time-zones): `range` preset (default `30d`) or `from`/`to`, plus `timezone` (default `UTC`). [Filters](#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`. |

get_event arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id`, `range`, `from`, `to`, `timezone`, `filters` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. [Period](#dates-and-time-zones): `range` preset (default `30d`) or `from`/`to`, plus `timezone` (default `UTC`). [Filters](#filters): optional. |
| `currency` | string | Main currency | ISO 4217 code such as `USD`, or `unknown`. Never converted or combined. |

get_conversions arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id` | shared | See notes | [Site](#choosing-a-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`. |

list_event_configs arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id` | shared | See notes | [Site](#choosing-a-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. |

configure_event arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id`, `filters` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. [Filters](#filters): optional. |
| `limit` | integer | 25 | 1 to 100. Maximum visitors to return. |

list_live_visitors arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id`, `range`, `from`, `to`, `timezone`, `filters` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. [Period](#dates-and-time-zones): `range` preset (default `30d`) or `from`/`to`, plus `timezone` (default `UTC`). [Filters](#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). |

list_visitors arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id` | shared | See notes | [Site](#choosing-a-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`. |

get_visitor arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. |

get_settings arguments:

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `site_id` | shared | See notes | [Site](#choosing-a-site): ID or domain, optional with one site. |
| `settings` | object | Required | At least one field. Omitted fields keep their value. Fields below. |

update_settings arguments:

```json
{
  "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](https://mrkr.app/docs/configure/cookieless-and-cookie-mode).
- Needs `owner` or `admin`. Every change is audited.
