What it does

Time-bucketed metric over a period. metric=pageviews includes AI-mediated human browsing (ai_user_action); metric=sessions and metric=visitors are browser-only, since server-side-ingested rows carry no session or visitor id — see traffic_class_breakdown for the AI-vs-direct split. metric=sessions counts sessions with at least one pageview in the bucket. metric=visitors is always 0 on privacy_mode=strict sites (no visitor IDs computed by design) — use sessions there. metric=events trends one named event (pass event_name) — the way to chart a conversion event over time, rather than calling event_details once per day; it counts rows like pageviews, so it includes AI-mediated human browsing.

Example prompts

Ask:

"Show me pageviews day-by-day for the last 30 days on mysite.com."
"Hourly visitor count for the last 24 hours."
"Weekly trend for sessions over the past quarter."
"Is the cta_click event trending up this month?"

A typical response:

Pageviews, daily, last 30 days for mysite.com:

  2026-04-20    1,847
  2026-04-21    1,920
  2026-04-22    2,114
  2026-04-23    8,412  ← spike (HN thread)
  ...
  2026-05-17    8,114
  2026-05-18    7,420
  2026-05-19    2,890

Returns an array of { ts, value } objects.

The metric argument controls what's measured: pageviews, visitors, sessions, or events. The last one trends a single named custom event over time — pass event_name alongside it (find names via list_events). The granularity argument controls bucket size: hour, day, or week. Long periods at hour-granularity return a lot of rows. Consider day or week for ranges over 30 days.

Counts include AI-mediated human browsing. See traffic_class_breakdown to see the AI-vs-direct split if it matters for your interpretation.

Pair with compare_periods for headline-style "is this up or down?" rather than the full day-by-day list.

Arguments

Name Type Required Description / Default
site_id string required Site identifier from list_sites (8-character base32, e.g. 'wjxayhdd').
metric string
enum: pageviews, visitors, sessions, events		 required Which metric to compute over the period. pageviews includes AI-mediated human browsing; sessions and visitors are browser-only. 'events' counts occurrences of the single event named in event_name (row count, like pageviews).
period string optional Time window. Keywords: today, yesterday, last_N_days (N from 1 to 730: today plus the N-1 days before, e.g. last_7_days, last_28_days), last_24_hours, this_week, last_week (weeks start on Monday), this_month, last_month, this_year, last_year, last_12_months. Or a custom date range YYYY-MM-DD..YYYY-MM-DD (inclusive). Days follow the site's timezone (list_sites; echoed as `timezone` in every response).
default: last_7_days
granularity string
enum: hour, day, week		 optional Time bucket size for the series. Use 'hour' for last_24h analysis, 'day' for week/month views, 'week' for quarter+.
default: day
event_name string optional Required when metric=events, rejected with any other metric. Case-sensitive event name — use list_events to discover the names this site actually sends. Counts match the total_count event_details reports for the same event and period (volume metric, includes AI-mediated human browsing).
filters object optional Optional segment filter. All given keys must match (AND; no OR, no negation); an empty string means not set. Keys: path (exact) or path_prefix; device_type, browser, os (exact, case-sensitive); referrer_host, utm_source, utm_medium, utm_campaign (exact); channel (search, ai_assistant, social, email, paid, campaign, referral, direct; as top_referrers group_by: channel assigns it). path/path_prefix match rows: pageviews count rows on matching paths, sessions/visitors count those with at least one matching row, and bounce_rate/avg_session_duration_seconds use all rows of those sessions. referrer_host, utm_* and channel match the session's entry (its first pageview in the period) and then select every row of the matching sessions, in every privacy mode. In top_entry_pages, top_referrers, top_sources and get_overview's top_source, path/path_prefix also test the entry: path_prefix '/blog/' there means sessions that entered on /blog/. Source and device filters make every number browser-only: server-side-ingested rows (including AI-mediated ai_user_action) have no session and no device fields, so they never match; the response then adds a `filter_note`. In get_overview, bot_share is null under any key other than path/path_prefix. With conversion_event the filter narrows the units; the conversion itself still counts anywhere in the period. The applied filters are echoed back as `filters`.

How to call it directly

If you're integrating from your own code rather than a chat client, this is the JSON-RPC payload:

curl -X POST https://mcp-analytics.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_timeseries",
    "arguments": {
      "site_id": "abc12345",
      "metric": "pageviews"
    }
  }
}'

Token comes from /settings after you sign up. Replace any required arguments above.

Related tools

  • top_pages: Most-viewed URL paths.
  • viewport_breakdown: Pageviews bucketed by viewport width: mobile_xs (<480), mobile (<768), tablet (<1024), desktop (<1440), desktop_xl (≥1440).
  • get_tracking_snippet: Return the HTML <script> snippet for a given site_id.
  • get_started_guide: Markdown walkthrough of the mcp-analytics workflow: adding sites, installing the tracker, querying analytics, custom events.
  • get_overview: TL;DR for the period: headline metrics (pageviews, visitors, sessions, bounce rate, avg session duration) plus pageviews_change_pct vs the previous equivalent window (same elapsed length; its bounds are returned in previous_period as local time with offset), top page, top traffic source, bot share, and top_events: the site's own events by count (up to 10; pageview and the engagement beacon are left out; list_events has them all).