get_organic_traffic - Docs di MetricSpot

Cosa fa questo strumento

get_organic_traffic restituisce uno snapshot a 28 giorni del traffico organico per un audit, estratto dalle property Google Analytics 4 e Google Search Console collegate dall’utente.

Restituisce connected: false se l’utente non ha ancora collegato Google, gli altri campi sono allora vuoti.
Quando collegato: sessions_28d (sessioni organiche totali), sessions_trend (serie giornaliera), top_landing_pages (URL + sessioni), top_queries (query + click + impression) e indexed_pages da GSC.
Cachato 24 ore lato server per audit, quindi le chiamate ripetute sono economiche e idempotenti.
Sempre legato a uno specifico audit_id; la finestra dati è relativa al created_at di quell’audit.

Perché è importante

Gli audit SEO senza dati di traffico dicono agli agenti cosa correggere, ma non cosa correggere per primo. get_organic_traffic permette a un agente di classificare le pagine fallite per valore organico reale, così le raccomandazioni atterrano su URL che davvero muovono fatturato.

Workflow concreti:

Un agente “da dove inizio?” chiama get_audit per i finding e get_organic_traffic per le sessioni, poi redige una fix-list ordinata per sessions_28d per landing page.
Un agente “query-gap” legge top_queries (alte impression, pochi click) e riscrive title e meta description della pagina corrispondente per alzare il CTR.

Come usarlo

L’utente deve prima collegare Google Analytics 4 e Search Console dentro la dashboard MetricSpot. Quando non è collegato, lo strumento ha comunque successo, restituisce connected: false così gli agenti possono degradare in modo elegante e dire all’utente come collegare Google.

Schema di input

{
  "type": "object",
  "properties": {
    "audit_id": { "type": "string", "minLength": 1 }
  },
  "required": ["audit_id"]
}

Esempio di schema di risposta

{
  "audit_id": "aud_01HZ8X9YP7K3T2N6Q5",
  "connected": true,
  "sessions_28d": 14328,
  "sessions_trend": [
    { "date": "2026-04-15", "sessions": 482 },
    { "date": "2026-04-16", "sessions": 511 },
    { "date": "2026-04-17", "sessions": 539 }
  ],
  "top_landing_pages": [
    { "url": "https://example.com/", "sessions": 5104 },
    { "url": "https://example.com/pricing", "sessions": 2871 },
    { "url": "https://example.com/blog/launch", "sessions": 1942 }
  ],
  "top_queries": [
    { "query": "example pricing", "clicks": 612, "impressions": 8412 },
    { "query": "example alternative", "clicks": 387, "impressions": 5101 }
  ],
  "indexed_pages": 184
}

Quando Google non è collegato:

{
  "audit_id": "aud_01HZ8X9YP7K3T2N6Q5",
  "connected": false,
  "sessions_28d": null,
  "indexed_pages": null
}

Claude Code

claude mcp add --transport http metricspot https://mcp.metricspot.com/mcp \
  --header "Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Prompt:

Per l’audit MetricSpot aud_01HZ8X9YP7K3T2N6Q5, estrai lo snapshot di traffico organico e dimmi quale query top-10 ha il CTR peggiore.

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "metricspot": {
      "url": "https://mcp.metricspot.com/mcp",
      "headers": {
        "Authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Prompt:

Combina i finding dell’audit con get_organic_traffic ed elenca le pagine fallite che portano più sessioni.

Python (classifica le pagine per traffico)

import httpx, json

HEADERS = {
    "content-type": "application/json",
    "accept": "application/json, text/event-stream",
    "authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx",
}

r = httpx.post("https://mcp.metricspot.com/mcp", headers=HEADERS, json={
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
        "name": "get_organic_traffic",
        "arguments": {"audit_id": "aud_01HZ8X9YP7K3T2N6Q5"},
    },
}, timeout=30.0)

snap = json.loads(r.json()["result"]["content"][0]["text"])
if not snap["connected"]:
    print("Connect GA4 + GSC at app.metricspot.com/settings/integrations")
else:
    for q in snap.get("top_queries", [])[:5]:
        ctr = q["clicks"] / q["impressions"] if q["impressions"] else 0
        print(f"{q['query']}: CTR {ctr:.1%} ({q['clicks']} / {q['impressions']})")

Node / TypeScript (HTTP grezzo)

const res = await fetch("https://mcp.metricspot.com/mcp", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    accept: "application/json, text/event-stream",
    authorization: "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
      name: "get_organic_traffic",
      arguments: { audit_id: "aud_01HZ8X9YP7K3T2N6Q5" },
    },
  }),
});
const snap = JSON.parse((await res.json()).result.content[0].text);
if (snap.connected) {
  console.log(`${snap.sessions_28d} sessions in last 28d`);
}

Errori comuni

Codice	Quando	Azione
`UNAUTHORIZED` (401)	Bearer token mancante o non valido	Genera una chiave su `https://app.metricspot.com/settings/api-keys`
`AUDIT_NOT_FOUND` (404)	`audit_id` non appartiene a questo account	Chiama `list_audits` per id validi
`FORBIDDEN` (403)	Il token non ha lo scope Google	Rigenera la chiave con gli scope di default dopo aver collegato Google
`UPSTREAM_FAILED` (5xx)	Disservizio della API GA4 o GSC	Riprova; la risposta è cachata 24h una volta riuscita

Domande frequenti

Perché `connected: false` anche se vedo traffico in GA4?

La connessione vive sul lato MetricSpot: l’utente deve visitare app.metricspot.com/settings/integrations e collegare Google Analytics 4 e Search Console esplicitamente. MetricSpot legge GA4 tramite l’Analytics Data API e GSC tramite la Search Console API; entrambe richiedono grant OAuth che l’utente autorizza una sola volta.

Perché una finestra di 28 giorni?

Corrisponde a come GSC riporta le sue top query per default ed è abbastanza corta per riflettere cambiamenti recenti (post-deploy, post-launch) e abbastanza lunga per smussare la stagionalità settimanale. La finestra non è configurabile in v1.

Quanto sono freschi i dati?

I dati GA4 sono tipicamente 24-48 ore indietro rispetto al tempo reale, secondo la finestra di processing di Google. I dati GSC hanno 2-3 giorni di ritardo. La risposta MCP è cachata 24 ore per audit_id lato server, quindi le chiamate ripetute nello stesso giorno restituiscono lo stesso snapshot.