Reader tools - Clickbase Docs

The Reader server (https://clickbase.so/mcp/reader) exposes read-only tools. None of them mutate anything — they are safe for reporting, analytics and Q&A agents. Every tool acts within your current team; a site parameter accepts the site’s domain or id.

Common parameters

Many tools share the same parameters. They are documented once here; each tool’s own table lists only the parameters specific to it plus a reference back to this section.

Parameter	Type	Description
`site`	string	The site domain or id. Required on every site-scoped tool. A site not in your current team fails with a clear, AI-actionable message.
`range`	string	Preset range — one of `today`, `yesterday`, `last_7_days`, `last_30_days`, `this_month`, `last_month`, `last_12_months`, `all` (default `today`). Ignored when `from` and `to` are given.
`from` / `to`	string	Custom range start / end as `Y-m-d`. Both must be given together.
`filters`	object	Dashboard filters as key/value pairs, e.g. `{"country": "US"}`. Standard allowed keys: `goal`, `prop_key`, `prop_value`, `path`, `entry_path`, `title`, `hostname`, `user_id`, `event_name`, `visit_count`, `referrer`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `browser`, `os`, `size`, `country`, `region`, `city`. `visit_count` uses `is:N` / `gte:N` / `lte:N`. Some tools accept a narrower key set (noted on the tool). Unknown keys are ignored.

Money values are always integer minor units (cents): 4990 = $49.90, never a decimal major-unit amount. Revenue tools distinguish client-verified Stripe/API money (the reserved event_name='payment' bucket) from client-reported event revenue. Paginated list tools take a page parameter (1-based, default 1) and return a meta block with integer total, current_page, last_page and per_page.

Sites & configuration

`list-sites-tool`

Read-only.

List the current team’s sites with period-scoped unique visitors, change versus the previous window, visitor/revenue sparklines, and a workspace summary. Optional filters: search (by domain), sort, and period (24h / 7d / 30d).

Parameters

Parameter	Type	Required	Description
`search`	string	No	Case-insensitive match against the site domain.
`sort`	string	No	One of `most_visitors`, `fewest_visitors`, `domain_asc`, `domain_desc` (default `most_visitors`).
`period`	string	No	One of `24h`, `7d`, `30d` (default `24h`).

Returns — sites (each with visitors, change, sparkline, revenue, revenue_sparkline, currency, has_revenue, …) and summary (visitors, revenue, currency, period). summary is always period revenue (payments/invoices in the window), not MRR.

search filters the sites array only — summary stays workspace-wide (same rule as the web dashboard).
A site-scoped personal access token narrows both sites and summary to the allowlist. Search still only filters sites; summary stays allowlist-wide.

`list-timezone-options-tool`

Read-only.

List every timezone identifier as a combobox option, for setting a site’s reporting timezone.

Parameters — none. Returns — a timezones array of combobox options.

`list-currency-options-tool`

Read-only.

List every supported reporting currency as a combobox option, for setting a site’s currency.

Parameters — none. Returns — a currencies array of combobox options.

Analytics

`get-site-overview-tool`

Read-only.

Topline analytics for one of the current team’s sites over a date range: pageviews, visitors, sessions, views per visit, bounce rate, average session duration, custom events, and (when present) revenue — each with the equivalent previous period for a delta. Revenue fields are integer minor units, i.e. cents (4990 = $49.90), never a decimal major-unit amount.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`range` / `from` / `to`	string	No	Date range — see Common parameters.

Returns — an overview object: pageviews, visitors, sessions, views_per_visit, bounce_rate, avg_session_seconds, custom_events, days, a nested previous period, and (only when either period has revenue) revenue and payments.

`get-timeseries-tool`

Read-only.

Per-bucket time series for one of the current team’s sites over a date range: parallel arrays of labels, visitors, pageviews, sessions, views per visit, bounce rate and average session duration — one entry per chart column. Also includes, when present, revenue/recurring_revenue series (and their new/renewal/refunds splits) plus mrr_change when Stripe is connected — integer minor units, i.e. cents (4990 = $49.90), never a decimal major-unit amount.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — a timeseries object of parallel arrays (labels, visitors, pageviews, sessions, views-per-visit, bounce rate, avg session duration, and revenue series when present).

`get-breakdown-tool`

Read-only.

Rank the values of one dimension (top pages, referrers, UTM tags, devices, locations, custom events, …) by volume for one of the current team’s sites over a date range, each row with its share of the total. Some dimensions’ rows also carry revenue/recurring_revenue (when present) — integer minor units, i.e. cents (4990 = $49.90), never a decimal major-unit amount.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`dimension`	string	Yes	The dimension to rank — one of `path`, `entry_path`, `exit_path`, `referrer_domain`, `channel`, `source`, `campaign`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `browser`, `os`, `device`, `screen`, `language`, `country`, `region`, `city`, `event_name`.
`limit`	int	No	Maximum number of rows to return (1–100, default 10).
`sort_by`	string	No	One of `visitors`, `revenue`, `recurring_revenue` (default `visitors`). The `event_name` dimension accepts only `visitors` — its revenue is client-reported, not payments.
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — a breakdown array of ranked rows (label, count, share, and revenue/recurring_revenue on money-bearing dimensions).

`get-location-details-tool`

Read-only.

Rank one session-entry location/technology dimension (country, region, city, browser, os, device, channel, source, referrer_domain) for one of the current team’s sites over a date range, the richer DETAILS drill-down: each row carries visitors (integer), bounce_rate and avg_session_seconds and percent (floats). Region/city rows also carry the entry country; source rows carry a representative domain for favicons.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`dimension`	string	No	The session-entry dimension — one of `country`, `region`, `city`, `browser`, `os`, `device`, `channel`, `source`, `referrer_domain` (default `country`).
`limit`	int	No	Maximum number of rows to return (1–500, default 250).
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — a rows array of ranked dimension rows (visitors, bounce_rate, avg_session_seconds, percent; plus entry country / representative domain where applicable).

`get-campaign-details-tool`

Read-only.

Campaign DETAILS drill-down for one of the current team’s sites over a date range: session-entry param=value rows (utm_source/medium/campaign/content/term and ref) with visitors (integer), bounce_rate, avg_session_seconds and percent (floats). Optional campaign_param narrows the union to one UTM/ref column; “all” (or absent) means every column.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`campaign_param`	string	No	Narrow the union to one column — one of `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `ref`, or `all` (default) for every column.
`limit`	int	No	Maximum number of rows to return (1–500, default 250).
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — a rows array of param=value entry rows (visitors, bounce_rate, avg_session_seconds, percent).

`get-page-details-tool`

Read-only.

Page DETAILS drill-down for one of the current team’s sites over a date range. The kind selects the report: “path” (Top pages: visitors, pageviews, bounce_rate, time_on_page_seconds, scroll_depth), “entry_path” (Entry pages: visitors, visits, bounce_rate, avg_session_seconds), or “exit_path” (Exit pages: visitors, visits, exit_rate). Counts are integers; rates/durations are floats; every row carries percent.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`kind`	string	No	Which page report — one of `path`, `entry_path`, `exit_path` (default `path`).
`limit`	int	No	Maximum number of rows to return (1–500, default 250).
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — a rows array of page rows for the chosen kind.

`list-filter-values-tool`

Read-only.

Distinct suggested values for ONE filter dimension on one of the current team’s sites over a date range — the Filter popover autocomplete. Returns values, each with value and label (both strings), ranked by volume. The requested dimension’s own active filter is stripped so alternatives still show; other active filters continue to narrow suggestions.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`dimension`	string	Yes	The filter dimension — one of `path`, `entry_path`, `title`, `hostname`, `user_id`, `event_name`, `referrer`, `channel`, `source`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `browser`, `os`, `size`, `country`, `region`, `city`.
`limit`	int	No	Maximum number of values to return (1–1000, default 1000).
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — a values array; each entry has value and label, ranked by volume.

Goals & funnels

`list-goals-tool`

Read-only.

List the goals defined on one of the current team’s sites, ordered by display name, 25 per page. Optionally filter by a case-insensitive display-name search. The meta block carries total/current_page/last_page/per_page as integers; pass page to navigate pages.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`search`	string	No	Case-insensitive match against the goal display name.
`page`	int	No	1-based page number (default 1). 25 goals per page.

Returns — a goals array (each: id, display_name, type, match_value, match_operator, scroll_threshold, currency, custom_props, created_at) and a meta pagination block.

`list-funnels-tool`

Read-only.

List the funnels defined on one of the current team’s sites, ordered by name, each with its step count.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.

Returns — a funnels array; each funnel has id, name, strict_order, steps_count, and created_at.

`get-goal-breakdown-tool`

Read-only.

Every goal’s conversions for one of the current team’s sites over a date range: converting visitors, total events, conversion rate and (when present) revenue per goal. Revenue is integer minor units, i.e. cents (4990 = $49.90), never a decimal major-unit amount.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — a goals array of per-goal conversion rows (converting visitors, total events, conversion rate, revenue).

`get-funnel-breakdown-tool`

Read-only.

A saved funnel’s per-step drop-off for one of the current team’s sites over a date range: each step’s visitors, drop-off and conversion rate, plus the entering / never-entering populations. Each step also carries revenue and its per-visitor average (value) — integer minor units, i.e. cents (4990 = $49.90), never a decimal major-unit amount.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`funnel`	string	Yes	The id of the funnel on this site.
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — a funnel object: per-step visitors, drop-off, conversion rate, revenue and per-visitor value, plus the entering / never-entering populations.

`evaluate-funnel-definition-tool`

Read-only.

Evaluate an ad hoc, unpersisted funnel definition (an ordered list of 2-8 inline steps) over a date range for one of the current team’s sites — a live preview, without ever saving a Funnel. Returns the same shape as a saved funnel’s breakdown, including per-step revenue and its per-visitor average (value) — integer minor units, i.e. cents (4990 = $49.90), never a decimal major-unit amount.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`steps`	object[]	Yes	Ordered 2–8 steps; array position is the step order. Each step: `match_type` (one of `page`, `event`, `scroll`, `outbound`, `download`, `button`, `form`, `copy`), `match_value` (required for page/event/scroll; optional for the autocapture types), `scroll_threshold` (required 0–100 for a scroll step).
`strict_order`	bool	No	Whether steps must be completed in the given order (default false).
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters. `goal`/`prop` keys are stripped (a funnel is itself a set of goal conditions).

Returns — a funnel object with the same shape as get-funnel-breakdown-tool (per-step drop-off, revenue and value).

Performance

`get-performance-overview-tool`

Read-only.

Site-wide Core Web Vitals percentiles (LCP, CLS, INP, FCP, TTFB at p50/p75/p90/p99) for one of the current team’s sites over a date range.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — an overview object of Web Vitals percentiles (LCP, CLS, INP, FCP, TTFB at p50/p75/p90/p99).

`get-performance-timeseries-tool`

Read-only.

Per-bucket Core Web Vitals percentiles for one of the current team’s sites over a date range — labels plus one point per chart column with event_count and LCP/CLS/INP/FCP/TTFB percentiles.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`group`	string	No	Bucket size — one of `five_minutes`, `ten_minutes`, `fifteen_minutes`, `thirty_minutes`, `hour`, `day`, `week`, `month`. Invalid or too-fine values fall back to the range default.
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — a timeseries object: labels plus one point per column with event_count and the LCP/CLS/INP/FCP/TTFB percentiles.

`get-performance-by-dimension-tool`

Read-only.

Rank Web Vitals by one dimension (path, country, region, device, browser, os) for one of the current team’s sites — each row with event_count and avg/percentile metrics.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`dimension`	string	Yes	The dimension to rank — one of `path`, `country`, `device`, `browser`, `os`, `region`.
`limit`	int	No	Maximum number of rows to return (1–100, default 100).
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — a breakdown array of ranked rows (each with event_count and avg/percentile metrics).

Sessions & journeys

`list-sessions-tool`

Read-only.

List visitor sessions for one of the current team’s sites over a date range, newest first. Each row aggregates one session: visitor/user identity, display_name, started_at/ended_at, duration in seconds, pageviews and events counts, entry/exit path, and device/geo/UTM context (durations and counts are integers). Optional thresholds narrow the list: identified_only, min_pageviews, min_events, min_duration. The meta block carries total/current_page/last_page/per_page as integers; pass page to navigate pages.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`identified_only`	bool	No	When true, only sessions belonging to an identified user (default false).
`min_pageviews`	int	No	Only sessions with at least this many pageviews (default 0).
`min_events`	int	No	Only sessions with at least this many custom events (default 0).
`min_duration`	int	No	Only sessions lasting at least this many seconds (default 0).
`page`	int	No	1-based page number (default 1).
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — a sessions array of session aggregates and a meta pagination block.

`get-session-timeline-tool`

Read-only.

The full event timeline for a single session on one of the current team’s sites: the session aggregate (identity, display_name, duration seconds, pageview/event counts, entry/exit path, device/geo/UTM, referrer) plus its chronological event list paginated by limit/offset. Counts and pagination.total are integers. Returns a null session when the id is unknown for this site — pick a session_id from ListSessions first.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`session_id`	string	Yes	The session UUID (from `list-sessions-tool`).
`limit`	int	No	Maximum number of timeline events to return (1–100, default 100).
`offset`	int	No	Number of timeline events to skip for paging (default 0).

Returns — a session aggregate (nullable), its chronological event list, and a pagination block with integer total.

`list-session-replays-tool`

Read-only.

List recorded session replays for one of the current team’s sites over a date range. Only sessions with a full snapshot and at least two events are returned. Optional min_duration filters by session length in seconds (default 30).

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`min_duration`	int	No	Minimum session duration in seconds (0–86400, default 30).
`page`	int	No	1-based page number (default 1).
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Reduced filter set — allowed keys: `path`, `browser`, `os`, `device` (or `size`), `country`. Unknown keys are ignored.

Returns — a replays array of replay summaries and a meta pagination block.

`get-session-replay-events-tool`

Read-only.

Fetch metadata and the hydrated rrweb event stream for one recorded session replay on a team site. Large payloads — prefer ListSessionReplays first to pick a session_id.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`session_id`	string	Yes	The session replay UUID.

Returns — the replay metadata plus the hydrated rrweb event stream. An unknown id is rejected with a clear message.

`get-journey-flow-tool`

Read-only.

The Sankey “flow” view of user journeys for one of the current team’s sites over a date range: the top limit most-followed FULL visitor sequences, steps columns deep. Each journey row carries an ordered path of {type, value} nodes, a visitors count (integer) and a percentage of all visitors. Consecutive repeats are collapsed and each sequence is truncated to steps nodes. Unlike GetJourneyNextSteps this returns the whole graph in one call, not an incremental drill-down.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`steps`	int	No	Columns (nodes deep) per journey, 2–10 (default 4). Out-of-range values are clamped.
`limit`	int	No	Maximum number of distinct journeys, 1–500 (default 50). Out-of-range values are clamped.
`stepFilters`	object	No	Optional per-column path filter keyed by 0-based step index (e.g. `{"0": "/pricing"}`). Plain value = case-insensitive contains; `` matches one path segment, `*` matches many.
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Reduced filter set (no `goal`/`prop` keys) — see Common parameters.

Returns — a journeys array; each row has an ordered path of {type, value} nodes, a visitors count and a percentage.

`get-journey-next-steps-tool`

Read-only.

GA4-style path exploration for one of the current team’s sites over a date range: the next (forward) or previous (backward) events every visitor did after an ordered step prefix, ranked by visitors. An empty steps array is the entry column (each visitor’s first/last event).

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`direction`	string	Yes	Journey direction: `forward` (next events) or `backward` (previous events).
`steps`	object[]	No	Ordered step prefix; each step `{type: "pageview"\|"event", value}`. Omit or pass `[]` for the entry column.
`search`	string	No	Optional case-insensitive substring to filter candidate labels.
`limit`	int	No	Maximum number of candidate rows to return (1–200, default 50).
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — a next_steps array of candidate next/previous events, ranked by visitors.

`get-journey-funnel-tool`

Read-only.

A journey funnel for one of the current team’s sites over a date range: cumulative visitor counts and per-step drop-off across an ordered sequence of at least two navigation steps.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`steps`	object[]	Yes	Ordered list of ≥2 steps, each `{type: "pageview"\|"event", value}`. Forward reads start-to-end; backward reads them as a suffix (steps[0] is the ending event).
`direction`	string	Yes	Journey direction: `forward` or `backward`.
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — a journey object: cumulative visitor counts and per-step drop-off.

`get-retention-cohorts-tool`

Read-only.

Cohort retention for one of the current team’s sites over a date range: visitors are grouped into a cohort by the period (day or week) of their first-ever event, then each cohort’s retention is tracked forward period by period. Returns cohorts keyed by cohort start date, each with an integer size and a percentages array (index 0 is always 100.0; a null entry means no data for that period), plus maxPeriods (integer) and the resolved mode.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`mode`	string	No	Cohort bucket: `week` (default) or `day`.
`range` / `from` / `to`	string	No	Date range — see Common parameters. Defaults to `last_30_days` for this tool (cohorts need a multi-period window).

Returns — a retention object: cohorts keyed by start date (each with size and percentages), plus maxPeriods and the resolved mode.

Events & errors

`list-events-tool`

Read-only.

Chronological Events LOG for one of the current team’s sites over a date range — raw individual events, newest first, excluding internal engagement beacons. Each row carries event_type, event_name, timestamp, path/url/title/hostname, user_id/visitor_id, display_name/avatar_url, country/device/browser/os, a properties map and (for error rows) error_id. Optional types narrows to a subset of event types. The meta block carries total/current_page/last_page/per_page as integers; pass page to navigate pages.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`types`	string[]	No	Subset of event types to include — any of `pageview`, `event`, `outbound`, `download`, `button`, `form`, `copy`, `error`. Empty lists every type.
`per_page`	int	No	Rows per page (1–100, default 50).
`page`	int	No	1-based page number (default 1).
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — an events array of raw event rows and a meta pagination block.

`get-events-timeseries-tool`

Read-only.

Per-bucket event counts for one of the current team’s sites over a date range — the Events explorer chart. Returns zero-filled parallel arrays: labels (one ISO timestamp per bucket), types (the event types present), series (a map of event_type to a list of integer counts aligned to labels), and group (the bucket size: hour/day/week/month). Engagement beacons are always excluded; optional types narrows the plotted series.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`types`	string[]	No	Subset of event types to plot — any of `pageview`, `event`, `outbound`, `download`, `button`, `form`, `copy`, `error`. Empty plots every type.
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — labels, types (present types), series (map of event_type → integer counts), and group (bucket size).

`get-event-property-breakdown-tool`

Read-only.

The per-event drill-down for one of the current team’s sites over a date range: the top event_properties key/value pairs recorded for ONE exact event_type/event_name pair, ranked by unique visitors. Returns rows, each with key (string), value (string) and visitors (integer). event_type must be one of the custom-event breakdown types (not pageview/engagement).

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`event_type`	string	Yes	The custom-event type to drill into — one of `event`, `outbound`, `download`, `button`, `form`, `copy`, `error`.
`event_name`	string	Yes	The exact event name to drill into.
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — a rows array; each row has key, value and visitors.

`list-page-titles-tool`

Read-only.

The Pages report for one of the current team’s sites over a date range: document titles ranked by sessions. Each row carries title, a representative path/hostname, integer pageviews/sessions, bounce_rate (float), time_on_page_seconds (float or null), integer sessions_previous and sessions_change_pct (float or null) vs the previous period. The meta block carries total/current_page/last_page/per_page as integers; pass page to navigate pages.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`per_page`	int	No	Rows per page (1–100, default 25).
`page`	int	No	1-based page number (default 1).
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — a page_titles array (title, representative path/hostname, pageviews, sessions, bounce_rate, time_on_page_seconds, previous-period comparison) and a meta pagination block.

`get-page-title-timeseries-tool`

Read-only.

Bucketed session counts for ONE document title on one of the current team’s sites over a date range — the Pages table sparkline. Returns zero-filled parallel arrays: labels (one ISO timestamp per bucket), values (integer session counts aligned to labels) and group (the bucket size: hour/day/week/month). An empty title returns empty arrays.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`title`	string	Yes	The exact document title to chart.
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — labels, values (integer session counts) and group (bucket size).

`list-error-names-tool`

Read-only.

Ranked distinct JavaScript error messages for one of the current team’s sites over a date range — the Errors report. Each row carries a stable id (the error fingerprint, pass it to get_error_by_id / get_error_timeseries / list_error_events), message, error_name, integer occurrences and sessions, ordered by occurrences descending. The meta block carries total/current_page/last_page/per_page as integers; pass page to navigate pages.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`per_page`	int	No	Rows per page (1–100, default 20).
`page`	int	No	1-based page number (default 1).
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — an errors array (each: id fingerprint, message, error_name, occurrences, sessions) and a meta pagination block.

`get-error-by-id-tool`

Read-only.

One error group’s summary for one of the current team’s sites over a date range: id (fingerprint), message, error_name, and integer occurrences/sessions. The error id comes from list_error_names. Identity resolves independently of the range (a known fingerprint never “disappears” when the window changes); the occurrence/session counts reflect the selected range/filters and may legitimately be zero.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`error`	string	Yes	The error fingerprint id (from `list-error-names-tool`).
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — an error object: id, message, error_name, occurrences, sessions.

`get-error-timeseries-tool`

Read-only.

Per-bucket occurrence counts for ONE error on one of the current team’s sites over a date range — the “errors over time” chart. Returns zero-filled parallel arrays: labels (one ISO timestamp per bucket), types (always [“error”]), series (a map of “error” to a list of integer counts aligned to labels), and group (the bucket size). The error id comes from list_error_names.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`error`	string	Yes	The error fingerprint id (from `list-error-names-tool`).
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — labels, types (always ["error"]), series (map "error" → integer counts) and group (bucket size).

`list-error-events-tool`

Read-only.

Individual occurrences of ONE error on one of the current team’s sites over a date range, newest first — the error detail occurrence list. Each row carries event_name, timestamp, path/url/title/hostname, user_id/visitor_id, display_name/avatar_url, country/device/browser/os, and the error detail (message, stack, file_name, line_number, column_number). The error id comes from list_error_names. The meta block carries total/current_page/last_page/per_page as integers; pass page to navigate pages.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`error`	string	Yes	The error fingerprint id (from `list-error-names-tool`).
`per_page`	int	No	Rows per page (1–100, default 20).
`page`	int	No	1-based page number (default 1).
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — an occurrences array of individual error rows (with the error detail) and a meta pagination block.

Realtime

`get-online-visitors-tool`

Read-only.

The number of distinct geolocated visitors currently online on one of the current team’s sites (active within the fixed 5-minute live window; engagement and payment events excluded). No date range — always “right now”.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — an online count of distinct visitors currently online.

`get-live-visitors-tool`

Read-only.

The visitors currently online on one of the current team’s sites — one row per geolocated visitor active within the fixed 5-minute live window (engagement and payment events excluded; location is the latest non-zero lat/lng), for the realtime globe. Each row carries visitor_id/user_id, is_identified, display_name/avatar_url, latitude/longitude, city/region/country, path, device/browser/os, source/channel/referrer_domain, last_seen_at, session_started_at and visit_count. No date range — always “right now”. Capped to the 500 most recent markers; the uncapped headline count is get_online_visitors.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — a visitors array; one row per online visitor (identity, geo, path, device, source, session_started_at, visit_count).

`get-live-activity-tool`

Read-only.

The live activity ticker for one of the current team’s sites — one row per geolocated visitor active inside the fixed 5-minute live window (engagement and payment events excluded), showing their latest non-engagement event, newest first. Each item carries display_name/avatar_url, country, path, event_type, event_name and timestamp. No date range — always “right now”.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`limit`	int	No	Number of ticker rows (1–100, default 20).
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — a feed array of recent visitors (latest activity each).

`get-live-source-domains-tool`

Read-only.

The source → representative favicon domain map for one of the current team’s sites, powering the live overlay’s source icons. Returns a source_domains object mapping each traffic source (e.g. “X (Twitter)”) to a canonical host (e.g. “x.com”), computed over a broad recent window so the domain is stable. No date range.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.

Returns — a source_domains object mapping each traffic source to a canonical host.

People

`list-site-users-tool`

Read-only.

List identified people (site users) for one of the current team’s sites, most recently seen first — the People/Users table. The list is scoped to profiles last seen inside the date range. Each row carries id, identifier, name, display_name, first_seen_at/last_seen_at, last-touch country/device/os/browser/source/referrer_domain, integer pageviews/sessions, revenue/recurring_revenue (integer minor units, i.e. cents), a 7-day activity_days flag array, and tracked. The meta block carries total/current_page/last_page/per_page as integers.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`per_page`	int	No	Rows per page (1–100, default 25).
`page`	int	No	1-based page number (default 1).
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — a users array of identified-person rows and a meta pagination block.

`get-site-user-profile-tool`

Read-only.

The full profile of one identified person (site user) for one of the current team’s sites over a date range: identity (identifier, name, display_name, avatar_url, custom traits), first/last seen, last-touch context, range metrics (integer pageviews/sessions, revenue/recurring_revenue in integer minor units, average duration_seconds), recent session cards, a ~26-week activity heatmap, and the chronological event timeline.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`site_user`	string	Yes	The site user id (from `list-site-users-tool`).
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — a profile object: identity + traits, first/last seen, last-touch context, range metrics, recent session cards, a ~26-week activity heatmap and the event timeline.

Revenue

Revenue tools report client-verified Stripe/API money (the reserved event_name='payment' bucket) in integer minor units (cents); refunds net negative. The channel/source/campaign breakdowns return only dimensions that took a payment in range, plus a synthetic Unattributed row. See the REST twin at /docs/api/revenue.

`get-mrr-summary-tool`

Read-only.

The recurring-revenue (MRR) card for one of the current team’s sites: current MRR and subscriber count, list-price net MRR change across the selected range, a monthly cumulative movement level / Instant subscribers series, and the currencies excluded from the money totals. Carries its own “connected” flag (false when no Stripe integration) so the empty state is explicit — read that, never gate on it yourself. All money is client-verified Stripe money in integer minor units, i.e. cents (4990 = $49.90), never a decimal major-unit amount.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`range` / `from` / `to`	string	No	Date range — see Common parameters.

Returns — an mrr object: current MRR and subscriber count, list-price change, cumulative monthly MRR/subscribers series, excluded currencies and a connected flag.

`get-ltv-summary-tool`

Read-only.

Customer Lifetime Value for one of the current team’s sites. Uses ChartMogul’s formula: ARPA ÷ a six-month trailing average of monthly customer churn (previous six months excluding the current month; missing months count as 0%). Returns current LTV, percent change vs the previous equal-length period, and a chart series. Money is integer minor units.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`range` / `from` / `to`	string	No	Date range — see Common parameters.

Returns — an ltv object: current LTV, change percent, and chart points.

`get-churn-rate-summary-tool`

Read-only.

Classic paid-subscriber (logo) churn rate for one of the current team’s sites. Per calendar month: net churned ÷ Instant subscribers at month start (ChartMogul Paid Subscriber / B2B; excludes same-month join+churn). Returns current rate, percent change vs the previous equal-length period, and a monthly chart series.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`range` / `from` / `to`	string	No	Date range — see Common parameters.

Returns — a churn_rate object: current rate, change percent, and chart points (churned, start_subscribers per month).

`get-channel-breakdown-tool`

Read-only.

Revenue by acquisition CHANNEL for one of the current team’s sites over a date range — the Revenue page’s channel donut. Returns {kpi, rows}; each row has label, count (visitors), percent, revenue, recurring_revenue and a nested top-sources list. Only channels that took at least one payment in range are returned, plus a synthetic “Unattributed” row (marked unattributed=true) for payments with no acquisition attribution. Revenue is CLIENT-VERIFIED Stripe/API money — the reserved event_name=‘payment’ bucket — not client-reported event revenue, in integer minor units, i.e. cents (4990 = $49.90); refunds net negative.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Filters as key/value pairs. Allowed keys as Common parameters minus `goal`. Unknown keys are ignored.

Returns — a breakdown object {kpi, rows}; each row has label, count, percent, revenue, recurring_revenue and a nested top-sources list.

`get-source-breakdown-tool`

Read-only.

Revenue by acquisition SOURCE (the referring site/host) for one of the current team’s sites over a date range. Returns {kpi, rows}; each row has label, count (visitors), percent, revenue and recurring_revenue. Only sources that took at least one payment in range are returned, plus a synthetic “Unattributed” row (marked unattributed=true) for payments with no acquisition attribution. Revenue is CLIENT-VERIFIED Stripe/API money — the reserved event_name=‘payment’ bucket — not client-reported event revenue, in integer minor units, i.e. cents (4990 = $49.90); refunds net negative.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Filters as key/value pairs. Allowed keys as Common parameters minus `goal`. Unknown keys are ignored.

Returns — a breakdown object {kpi, rows}; each row has label, count, percent, revenue and recurring_revenue.

`get-campaign-breakdown-tool`

Read-only.

Revenue by acquisition CAMPAIGN (utm_campaign) for one of the current team’s sites over a date range. Returns {kpi, rows}; each row has label, count (visitors), percent, revenue and recurring_revenue. Only campaigns that took at least one payment in range are returned, plus a synthetic “Unattributed” row (marked unattributed=true) for payments with no acquisition attribution. Revenue is CLIENT-VERIFIED Stripe/API money — the reserved event_name=‘payment’ bucket — not client-reported event revenue, in integer minor units, i.e. cents (4990 = $49.90); refunds net negative.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Filters as key/value pairs. Allowed keys as Common parameters minus `goal`. Unknown keys are ignored.

Returns — a breakdown object {kpi, rows}; each row has label, count, percent, revenue and recurring_revenue.

`list-payments-tool`

Read-only.

The most recent payments for one of the current team’s sites over a date range, newest first. Each row: transaction id, amount, currency, recurring/refunded/renewal/free-trial flags, provider, customer email/name, visitor id and occurred-at. Amounts are client-verified Stripe/API money in integer minor units, i.e. cents (4990 = $49.90); a refund is a negative amount with refunded=true.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`range` / `from` / `to`	string	No	Date range — see Common parameters.

Returns — a payments array of recent payment rows.

`list-site-subscriptions-tool`

Read-only.

The most recently started subscriptions for one of the current team’s sites over a date range (ranged on start date), newest first. Every status is included, canceled ones too — this is a ledger, not the live-MRR sum. Each row: subscription id, customer id/name/email, status, mrr_amount, currency, provider and the started/canceled/current-period-end timestamps. mrr_amount is a client-verified Stripe monthly figure in integer minor units, i.e. cents (4900 = $49.00).

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`range` / `from` / `to`	string	No	Date range — see Common parameters.

Returns — a subscriptions array (subscription id, customer, status, mrr_amount, currency, provider, lifecycle timestamps).

Stripe

`get-stripe-integration-tool`

Read-only.

Get one of the current team’s sites’ Stripe integration status. When connected, also returns the account currency, the product allowlist and backfill sync progress (sync.processed_count values are integer counts). Never exposes the API key or webhook secret.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.

Returns — an integration object: connection status, account currency, product allowlist and sync backfill progress. The API key and webhook secret are never exposed.

Search Console

`get-search-console-keywords-tool`

Read-only.

Return organic Google Search keyword stats (clicks, impressions, CTR, position, estimated revenue) for one of the current team’s sites from its connected Search Console property over a date range: each row carries label (query), visitors (integer clicks), impressions (integer), ctr and position (floats) and revenue (integer cents). The rows are empty with an “error” of “not_connected” when the site has not connected Search Console — the connect flow itself is web-only.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`limit`	int	No	Maximum number of keyword rows to return (1–500, default 10).
`page`	int	No	Zero-based page of keyword rows (0–100, default 0).
`search`	string	No	Optional case-insensitive substring to filter keywords by.
`range` / `from` / `to`	string	No	Date range — see Common parameters.
`filters`	object	No	Dashboard filters — see Common parameters.

Returns — a rows array of keyword stats (label, clicks, impressions, ctr, position, revenue); an error of "not_connected" when the site has no Search Console property.

Annotations

`list-annotations-tool`

Read-only.

List the annotations pinned to one of the current team’s site charts within a date range. An annotation marks a date on the charts with a note (e.g. “launched pricing change”, “ran a promo”), ordered chronologically.

Parameters

Parameter	Type	Required	Description
`site`	string	Yes	See Common parameters.
`range` / `from` / `to`	string	No	Date range — see Common parameters.

Returns — an annotations array of chart annotations, ordered chronologically.

​Common parameters

​Sites & configuration

​list-sites-tool

​list-timezone-options-tool

​list-currency-options-tool

​Analytics

​get-site-overview-tool

​get-timeseries-tool

​get-breakdown-tool

​get-location-details-tool

​get-campaign-details-tool

​get-page-details-tool

​list-filter-values-tool

​Goals & funnels

​list-goals-tool

​list-funnels-tool

​get-goal-breakdown-tool

​get-funnel-breakdown-tool

​evaluate-funnel-definition-tool

​Performance

​get-performance-overview-tool

​get-performance-timeseries-tool

​get-performance-by-dimension-tool

​Sessions & journeys

​list-sessions-tool

​get-session-timeline-tool

​list-session-replays-tool

​get-session-replay-events-tool

​get-journey-flow-tool

​get-journey-next-steps-tool

​get-journey-funnel-tool

​get-retention-cohorts-tool

​Events & errors

​list-events-tool

​get-events-timeseries-tool

​get-event-property-breakdown-tool

​list-page-titles-tool

​get-page-title-timeseries-tool

​list-error-names-tool

​get-error-by-id-tool

​get-error-timeseries-tool

​list-error-events-tool

​Realtime

​get-online-visitors-tool

​get-live-visitors-tool

​get-live-activity-tool

​get-live-source-domains-tool

​People

​list-site-users-tool

​get-site-user-profile-tool

​Revenue

​get-mrr-summary-tool

​get-ltv-summary-tool

​get-churn-rate-summary-tool

​get-channel-breakdown-tool

​get-source-breakdown-tool

​get-campaign-breakdown-tool

​list-payments-tool

​list-site-subscriptions-tool

​Stripe

​get-stripe-integration-tool

​Search Console

​get-search-console-keywords-tool

​Annotations

​list-annotations-tool

Common parameters

Sites & configuration

`list-sites-tool`

`list-timezone-options-tool`

`list-currency-options-tool`

Analytics

`get-site-overview-tool`

`get-timeseries-tool`

`get-breakdown-tool`

`get-location-details-tool`

`get-campaign-details-tool`

`get-page-details-tool`

`list-filter-values-tool`

Goals & funnels

`list-goals-tool`

`list-funnels-tool`

`get-goal-breakdown-tool`

`get-funnel-breakdown-tool`

`evaluate-funnel-definition-tool`

Performance

`get-performance-overview-tool`

`get-performance-timeseries-tool`

`get-performance-by-dimension-tool`

Sessions & journeys

`list-sessions-tool`

`get-session-timeline-tool`

`list-session-replays-tool`

`get-session-replay-events-tool`

`get-journey-flow-tool`

`get-journey-next-steps-tool`

`get-journey-funnel-tool`

`get-retention-cohorts-tool`

Events & errors

`list-events-tool`

`get-events-timeseries-tool`

`get-event-property-breakdown-tool`

`list-page-titles-tool`

`get-page-title-timeseries-tool`

`list-error-names-tool`

`get-error-by-id-tool`

`get-error-timeseries-tool`

`list-error-events-tool`

Realtime

`get-online-visitors-tool`

`get-live-visitors-tool`

`get-live-activity-tool`

`get-live-source-domains-tool`

People

`list-site-users-tool`

`get-site-user-profile-tool`

Revenue

`get-mrr-summary-tool`

`get-ltv-summary-tool`

`get-churn-rate-summary-tool`

`get-channel-breakdown-tool`

`get-source-breakdown-tool`

`get-campaign-breakdown-tool`

`list-payments-tool`

`list-site-subscriptions-tool`

Stripe

`get-stripe-integration-tool`

Search Console

`get-search-console-keywords-tool`

Annotations

`list-annotations-tool`