MCP
Reader tools
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.
searchfilters thesitesarray only —summarystays workspace-wide (same rule as the web dashboard).- A site-scoped personal access token narrows both
sitesandsummaryto the allowlist. Search still only filterssites;summarystays 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=valuerows (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
kindselects 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
metablock carries total/current_page/last_page/per_page as integers; passpageto 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
metablock carries total/current_page/last_page/per_page as integers; passpageto 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.totalare integers. Returns a nullsessionwhen 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
limitmost-followed FULL visitor sequences,stepscolumns deep. Each journey row carries an orderedpathof {type, value} nodes, avisitorscount (integer) and apercentageof all visitors. Consecutive repeats are collapsed and each sequence is truncated tostepsnodes. 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
cohortskeyed by cohort start date, each with an integersizeand apercentagesarray (index 0 is always 100.0; a null entry means no data for that period), plusmaxPeriods(integer) and the resolvedmode.
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
typesnarrows to a subset of event types. Themetablock carries total/current_page/last_page/per_page as integers; passpageto 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), andgroup(the bucket size: hour/day/week/month). Engagement beacons are always excluded; optionaltypesnarrows 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
metablock carries total/current_page/last_page/per_page as integers; passpageto 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) andgroup(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, integeroccurrencesandsessions, ordered by occurrences descending. Themetablock carries total/current_page/last_page/per_page as integers; passpageto 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 integeroccurrences/sessions. Theerrorid 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), andgroup(the bucket size). Theerrorid 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
errorid comes from list_error_names. Themetablock carries total/current_page/last_page/per_page as integers; passpageto 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_domainsobject 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. Themetablock 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.