GET /api/audits/:id/google - Docs de MetricSpot

Qué hace este endpoint

GET /api/audits/:id/google devuelve el snapshot de tráfico orgánico de una auditoría, leído desde la propiedad de Google Analytics 4 y el sitio de Google Search Console que el usuario tenga vinculados.

Devuelve { "connected": false } cuando el usuario aún no ha vinculado Google.
Devuelve { "connected": true, "linked": false } cuando Google está conectado pero la URL de la auditoría no tiene mapeo a una propiedad GA4 ni a un sitio GSC.
Cuando ambos están conectados y mapeados, devuelve el snapshot completo: tráfico GA4, queries GSC y extras de indexación.
Cacheado en servidor 24 horas por (user_id, url), así que llamadas repetidas en un día son baratas e idempotentes.
Solo Pro y gateado por el scope OAuth de Google: devuelve 403 si el token no tiene acceso a Google o el plan no incluye la integración.

Por qué importa

Las auditorías sin datos de tráfico le dicen al agente qué arreglar, no qué arreglar primero. El snapshot de tráfico orgánico permite a un agente ordenar las páginas fallidas por valor orgánico real para que las recomendaciones aterricen en URLs que de verdad mueven ingresos.

Workflows concretos:

Un agente “¿por dónde empiezo?” llama a GET /api/audits/:id para los findings y a GET /api/audits/:id/google para sesiones, y luego redacta una lista de arreglos ordenada por sesiones 28d por landing.
Un agente de query-gap lee gsc.top_queries (muchas impresiones, CTR bajo) y reescribe título y meta descripción de la página afectada para subir el CTR.

Cómo usarlo

El usuario debe conectar Google Analytics 4 y Search Console dentro del panel de MetricSpot primero, y luego mapear explícitamente cada URL auditada a una propiedad GA4 y a un sitio GSC. Sin mapeo, el endpoint sigue funcionando con linked: false para que los agentes se degraden con elegancia.

Petición

GET /api/audits/12345/google HTTP/1.1
Host: app.metricspot.com
Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx

curl

curl https://app.metricspot.com/api/audits/12345/google \
  -H "authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Node fetch

const res = await fetch("https://app.metricspot.com/api/audits/12345/google", {
  headers: { authorization: "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx" },
});
const data = await res.json();

if (!data.connected) {
  console.log("Vincula Google en app.metricspot.com/settings/integrations");
} else if (!data.linked) {
  console.log("Mapea esta URL a una propiedad GA4 y a un sitio GSC desde el panel");
} else {
  console.log(`Sesiones 28d: ${data.ga4?.sessions_28d}`);
  for (const q of data.gsc?.top_queries?.slice(0, 5) ?? []) {
    const ctr = q.impressions ? q.clicks / q.impressions : 0;
    console.log(`${q.query}: CTR ${(ctr * 100).toFixed(1)}%`);
  }
}

Python httpx

import httpx

r = httpx.get(
    "https://app.metricspot.com/api/audits/12345/google",
    headers={"authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=30.0,
)
data = r.json()
if not data.get("connected"):
    print("Vincula Google en app.metricspot.com/settings/integrations")
elif not data.get("linked"):
    print("Mapea esta URL a una propiedad GA4 y a un sitio GSC")
else:
    print("Sesiones 28d:", (data.get("ga4") or {}).get("sessions_28d"))

Respuesta

Conectado y mapeado

200 OK:

{
  "connected": true,
  "linked": true,
  "ga4": {
    "sessions_28d": 14328,
    "sessions_trend": [
      { "date": "2026-04-16", "sessions": 482 },
      { "date": "2026-04-17", "sessions": 511 }
    ],
    "top_landing_pages": [
      { "url": "https://example.com/", "sessions": 5104 },
      { "url": "https://example.com/pricing", "sessions": 2871 }
    ]
  },
  "gsc": {
    "top_queries": [
      { "query": "example pricing", "clicks": 612, "impressions": 8412, "position": 4.2 },
      { "query": "example alternative", "clicks": 387, "impressions": 5101, "position": 7.8 }
    ],
    "indexing": {
      "indexed_pages": 184,
      "coverage_issues": 3
    }
  },
  "ga_property_used": {
    "property_id": "properties/123456789",
    "display_name": "Example - GA4"
  },
  "gsc_site_used": {
    "site_url": "https://example.com/"
  }
}

Campos:

connected: true si la cuenta tiene un grant OAuth de Google vivo. false y se omite el resto si no hay grant.
linked: true si la URL de esta auditoría tiene mapeo a una propiedad GA4 o a un sitio GSC. false significa que el usuario debe mapearla en el panel.
ga4.sessions_28d: total de sesiones orgánicas en los últimos 28 días.
ga4.sessions_trend: serie diaria de sesiones orgánicas, la más antigua primero.
ga4.top_landing_pages: array { url, sessions }, ordenado por sesiones desc.
gsc.top_queries: array { query, clicks, impressions, position }, ordenado por clicks desc.
gsc.indexing: objeto opcional con indexed_pages y coverage_issues de GSC.
ga_property_used / gsc_site_used: el mapeo que usó la auditoría, para mostrar.

Conectado pero sin mapeo

{ "connected": true, "linked": false }

Sin conectar

{ "connected": false }

Reauth requerido

Cuando el token OAuth guardado no se puede refrescar (revocado o expirado más allá del refresh), la fila de conexión se elimina y el endpoint devuelve:

{ "connected": false, "reason": "reauth_required" }

Errores comunes

Código	Cuándo	Acción
`UNAUTHORIZED` (401)	Bearer ausente o inválido	Crea una clave en `app.metricspot.com/settings/api-keys`
`FORBIDDEN` (403)	El plan no incluye integraciones Google, o la auditoría es de otra cuenta	Sube a Pro, o usa la cuenta propietaria
`AUDIT_NOT_FOUND` (404)	El id de auditoría no existe	Pasa una auditoría que poseas
`INVALID_URL` (400)	`:id` no es un entero positivo	Pasa un id entero
`UPSTREAM_FAILED` (5xx)	Caída de la API de GA4 o GSC	Reintenta; la respuesta queda cacheada 24h una vez correcta

Preguntas frecuentes

¿Por qué `linked: false` si veo tráfico en GA4?

El vínculo es por URL del lado de MetricSpot. Tras conectar Google en app.metricspot.com/settings/integrations, también hay que mapear cada URL auditada a una propiedad GA4 y a un sitio GSC concretos. MetricSpot lo hace así porque una cuenta de Google suele tener muchas propiedades GA4; el mapeo explícito evita coger la equivocada.

¿Por qué una ventana de 28 días?

Coincide con cómo GSC reporta sus top queries por defecto y es suficientemente corta para reflejar cambios recientes (postdeploy, postlanzamiento) y suficientemente larga para suavizar la estacionalidad semanal. La ventana no es configurable en v1.

¿Cómo de fresca es la data?

Los datos de GA4 suelen ir entre 24 y 48 horas detrás del tiempo real, según la ventana de procesado de Google. GSC va 2 a 3 días por detrás. El endpoint cachea respuestas correctas 24 horas por (user_id, url), así que llamadas repetidas el mismo día devuelven el mismo snapshot.

¿Consume cupo de auditorías?

No. Este endpoint no consume más allá del plan del usuario y la cuota de la API de Google. La caché de 24 horas también garantiza que un bucle CI martilleando este endpoint no agote los límites diarios de Google.