What it does

Top referring hosts. Attribution metric — counts direct browser visits only ('user' class). AI-mediated traffic (Claude/ChatGPT fetching on a user's behalf) is excluded because the AI sets its own host as referrer or strips it; including it would inflate 'direct' or 'claude.ai' without telling you where the human attention actually came from. Counted once per session (field `sessions`), from the host the session entered on — not once per pageview, so don't compare it against pageview counts. percentage_of_total is a percentage of all referred sessions: 58.3 means 58.3%.

Example prompts

Ask:

"Where is mysite.com traffic coming from this week?"
"Top referrers for the last 30 days, anything new?"
"Show me my top 20 referrers."

A typical response:

Top referrers for mysite.com (last 7 days):

  news.ycombinator.com   1,847 sessions
  twitter.com              612 sessions
  reddit.com               487 sessions
  bluesky.app              312 sessions
  dev.to                   258 sessions
  google.com (organic)     244 sessions
  perplexity.ai            147 sessions  (AI-mediated human)
  chatgpt.com              124 sessions  (AI-mediated human)
  duckduckgo.com            89 sessions
  linkedin.com              71 sessions

Returns an array of { referrer_host, sessions } objects. Counted once per session, from the source the session entered on — not once per pageview.

Attribution metric: counts direct browser visits only (the user traffic class). AI-mediated traffic (ai_user_action, i.e. Claude or ChatGPT fetching on a user's behalf) is excluded from this list, because the AI sets its own host as the referrer or strips it. Including it would inflate "direct" or "claude.ai" without telling you where the human attention actually came from. Use traffic_class_breakdown to see the AI-mediated share separately.

The "AI-mediated human" lines above (perplexity.ai, chatgpt.com) ARE included here. Those are humans clicking through from those services in their browser, not the AI fetching for them. That distinction matters for understanding AI's role in your acquisition funnel.

Arguments

Name Type Required Description / Default
site_id string required Site identifier from list_sites (8-character base32, e.g. 'wjxayhdd').
period string optional Time window. Keywords: today, yesterday, last_7_days, last_30_days, last_90_days, last_12_months. Or a custom date range YYYY-MM-DD..YYYY-MM-DD (inclusive).
default: last_7_days
limit integer optional Maximum number of rows to return. Capped at 1000 server-side.
default: 10
conversion_event string optional Optional custom event name (case-sensitive, from list_events) to treat as the conversion. Each row then gains conversion_base (units in that row), converted (how many of them fired the event anywhere in the period) and conversion_rate (ratio 0–1: 0.05 means 5%; null when no unit is attributed to the row: it has no browser sessions/visitors at all, e.g. purely server-ingested traffic, or — on privacy_mode=all sites in top_referrers/top_sources/top_entry_pages — the row was never any visitor's first entry in the period, even though it has sessions). The response gains a site-wide `conversion` block: conversion_base (units in the period), converted (how many fired the event), conversion_rate (ratio 0–1: 0.05 means 5%), `unit` and a `note` to relay. Use it to compare conversion rates between rows — absolute counts alone favour whatever row has the most traffic. The unit depends on the site's privacy_mode: 'session' on strict and balanced sites (no identity survives UTC midnight there, so only conversions within one visit count), 'visitor' on privacy_mode=all sites (first-party cookie, so a visitor who arrives Monday and converts Thursday counts as converted, if both days are inside the period). The auto-tracked 'pageview' and 'engagement' are rejected — pick one of the site's own events.

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": "top_referrers",
    "arguments": {
      "site_id": "abc12345"
    }
  }
}'

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

Related tools

  • top_pages: Most-viewed URL paths.
  • breakdown: Breakdown of visits by browser, os, device_type, or country (country empty in MVP).
  • get_timeseries: Time-bucketed metric over a period.
  • 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, top page, top traffic source, bot share, and top 3 custom events.
  • engagement_overview: Real reading time + scroll depth from the engagement beacon (fired on pagehide).