Grounding Audit

Grounding Audit responde a la pregunta: «¿Un LLM citaría siquiera esta página como fuente — y si no, por qué?». Le pasas una URL, una lista de URLs o un sitemap.xml. Rankion descarga las páginas, las ejecuta por un pipeline de checks basado en reglas y te devuelve un score (0–100), un tier (not-grounded/weak/partial/grounded) y findings estructurados con un fix concreto por issue. Todo async vía REST — se acabaron las requests de 90 segundos.

Qué puede hacer

• Auditoría de URL única — envías una URL, recibes 202 + audit_id, haces polling del estado.
• Auditoría bulk — dispatch de hasta varios centenares de URLs en un solo batch, batch_id compartido, webhook compartido.
• Auditoría de sitemap — pasas un sitemap.xml, Rankion lo parsea (incluida recursión de sitemap-index), filtra con include_patterns/exclude_patterns y lanza el batch.
• Stream NDJSON — los resultados del batch se leen línea por línea, sin cargar un JSON-blob entero.
• Webhooks firmados HMAC — batch terminado → POST a tu callback_url con header X-Rankion-Signature (SHA-256, 4 reintentos).
• Findings estructurados — por issue: id, severity (critical/high/medium/low/info), framework (v1.5/eeat/people-first), title, description, fix.type, fix.action y URL al spec.
• Lógica de tier — TierThresholds: 0–25 not-grounded, 26–50 weak, 51–75 partial, 76–100 grounded.

Cuándo usarlo

• Has publicado un pillar article y quieres saber si en su forma actual los LLM lo citarían.
• Quieres revisar todo el sitio para citation-readiness en lugar de ir URL por URL.
• Operas tus propios pipelines (CI, hook post-publish del CMS) y necesitas los datos vía webhook.
• AI Visibility Tracking te marca como «no citado» y quieres saber qué páginas hay que arreglar.

Workflow

1. Iniciar single — POST /v1/grounding/analyze con {url, frameworks?:["v1.5"]}. Devuelve 202 + audit_id + poll_endpoint.
2. Polling — GET /v1/grounding/audits/{id} hasta status=completed. Devuelve score, tier, findings[], raw_text.
3. Bulk — POST /v1/grounding/batch con urls[] y opcionalmente callback_url. Devuelve batch_id + callback_secret (una sola vez — guárdalo!).
4. Sitemap — POST /v1/grounding/sitemap-audit con sitemap_url, opcionalmente include_patterns/exclude_patterns. Los créditos se cargan TRAS el parse.
5. Recoger resultados — GET /v1/grounding/batches/{id} (resumen) o …/results.ndjson (stream línea a línea).

Umbrales de tier

API

Throttling: analyze 30/min, batch + sitemap 5/min, polling 120/min. Auth: token Sanctum.

Límites conocidos

• Frameworks eeat + people-first están como stub en la pipeline REST hoy — v1.5 es el framework que corre end-to-end.
• Concurrencia por batch no está garantizada. Concurrency efectiva = 5 workers a nivel servidor. El parámetro concurrency es hint, no contrato.
• Sin auto-refund en fallos de auditoría. Las auditorías de sitemap cobran créditos TRAS el parse — no sabes el conteo exacto de URLs hasta que se aplica el filtrado.
• TTL — los resultados expiran soft a los 30 días y se borran en duro a los 90. Persiste tú mismo si necesitas histórico de largo plazo.

Módulos relacionados

• AI-Visibility Tracking — mide si tus páginas realmente aparecen en respuestas de LLMs. Grounding Audit explica por qué (o por qué no).
• Content Audit — issues SEO clásicos. Grounding Audit hace zoom en citation-readiness para LLMs.
• Page Deep Audit — chequeo SEO/performance más profundo por URL.
• Agentic Chat — el master agent puede lanzar grounding audits directamente desde el chat.