get_organic_traffic - Docs de MetricSpot

Què fa aquesta eina

get_organic_traffic retorna una instantània de 28 dies de tràfic orgànic per a una auditoria, obtinguda de les propietats de Google Analytics 4 i Google Search Console vinculades per l’usuari.

Retorna connected: false si l’usuari encara no ha vinculat Google: la resta de camps queden buits.
Quan està connectat: sessions_28d (total de sessions orgàniques), sessions_trend (sèrie diària), top_landing_pages (URL + sessions), top_queries (query + clicks + impressions), i indexed_pages de GSC.
Cache de 24 hores al servidor per auditoria, així que les crides repetides són econòmiques i idempotents.
Sempre lligada a un audit_id específic; la finestra de dades és relativa al created_at d’aquesta auditoria.

Per què importa

Les auditories SEO sense dades de tràfic diuen als agents què cal arreglar, però no què cal arreglar primer. get_organic_traffic permet a un agent ordenar les pàgines amb errors per valor orgànic real perquè les recomanacions aterrin a URLs que realment mouen ingressos.

Fluxos concrets:

Un agent “per on començo?” crida get_audit per als findings i get_organic_traffic per a les sessions, i redacta una llista de correccions ordenada per sessions_28d per landing page.
Un agent de buits de queries llegeix top_queries (impressions altes, clicks baixos) i reescriu el title i la meta description de la pàgina coincident per pujar el CTR.

Com utilitzar-la

L’usuari primer ha de connectar Google Analytics 4 i Search Console des del dashboard de MetricSpot. Quan no està connectat, l’eina encara respon correctament: retorna connected: false perquè els agents puguin degradar sense problemes i dir a l’usuari com vincular Google.

Esquema d’entrada

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

Mostra de l’esquema de resposta

{
  "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
}

Quan Google no està vinculat:

{
  "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:

For MetricSpot audit aud_01HZ8X9YP7K3T2N6Q5, pull the organic traffic snapshot and tell me which top-10 query has the worst CTR.

Cursor

.cursor/mcp.json:

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

Prompt:

Combine the audit findings with get_organic_traffic and list the failing pages that bring in the most sessions.

Python (ordenar pàgines per tràfic)

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 en cru)

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`);
}

Errors habituals

Codi	Quan	Acció
`UNAUTHORIZED` (401)	Token Bearer absent o invàlid	Emet una clau a `https://app.metricspot.com/settings/api-keys`
`AUDIT_NOT_FOUND` (404)	`audit_id` no pertany al teu compte	Crida `list_audits` per a ids vàlids
`FORBIDDEN` (403)	El token no té l’scope de Google	Reemet la clau amb els scopes per defecte després de vincular Google
`UPSTREAM_FAILED` (5xx)	Caiguda de l’API de GA4 o GSC	Reintenta; la resposta es cacheja 24h un cop té èxit

Preguntes freqüents

Per què `connected: false` si veig tràfic a GA4?

La connexió viu al costat de MetricSpot: l’usuari ha de visitar app.metricspot.com/settings/integrations i vincular Google Analytics 4 i Search Console explícitament. MetricSpot llegeix GA4 via l’Analytics Data API i GSC via la Search Console API; tots dos requereixen grants OAuth que l’usuari autoritza un cop.

Per què una finestra de 28 dies?

Coincideix amb com GSC reporta les seves top queries per defecte, i és prou curta per reflectir canvis recents (post-deploy, post-llançament) i prou llarga per suavitzar la estacionalitat setmanal. La finestra no és configurable a la v1.

Quina frescor té la dada?

Les dades de GA4 normalment van 24-48 hores per darrere del temps real, segons la finestra de processament de Google. Les dades de GSC tenen 2-3 dies de retard. La resposta MCP es cacheja 24 hores per audit_id al servidor, així que les crides repetides el mateix dia retornen la mateixa instantània.