Grounding Audit

Grounding Audit répond à la question : « Un LLM citerait-il seulement cette page comme source — et si non, pourquoi ? ». Tu lui passes une URL, une liste d'URL ou un sitemap.xml. Rankion va chercher les pages, les fait passer dans une pipeline de checks basée sur des règles et te renvoie un score (0–100), un tier (not-grounded/weak/partial/grounded) et des findings structurés avec un fix concret par issue. Tout en async via REST — finis les requêtes de 90 secondes.

Ce qu'il peut faire

• Audit d'une URL — soumets une URL, reçois 202 + audit_id, fais le polling du statut.
• Audit bulk — dispatch jusqu'à plusieurs centaines d'URL dans un seul batch, batch_id partagé, webhook partagé.
• Audit de sitemap — passe un sitemap.xml, Rankion le parse (avec récursion sur les sitemap-index), filtre via include_patterns/exclude_patterns et lance le batch.
• Stream NDJSON — les résultats du batch se lisent ligne par ligne, sans charger un JSON-blob entier.
• Webhooks signés HMAC — batch terminé → POST vers ton callback_url avec header X-Rankion-Signature (SHA-256, 4 retries).
• Findings structurés — par issue : id, severity (critical/high/medium/low/info), framework (v1.5/eeat/people-first), title, description, fix.type, fix.action et URL vers le spec.
• Logique de tier — TierThresholds : 0–25 not-grounded, 26–50 weak, 51–75 partial, 76–100 grounded.

Quand l'utiliser

• Tu viens de publier un pillar article et tu veux savoir si, en l'état, les LLM le citeraient.
• Tu veux scanner tout le site sur la citation-readiness au lieu de cliquer URL par URL.
• Tu fais tourner tes propres pipelines (CI, hook post-publish du CMS) et tu as besoin des données via webhook.
• AI Visibility Tracking t'a marqué « non cité » et tu veux savoir quelles pages sont à reprendre.

Workflow

1. Lancer un audit unique — POST /v1/grounding/analyze avec {url, frameworks?:["v1.5"]}. Renvoie 202 + audit_id + poll_endpoint.
2. Polling — GET /v1/grounding/audits/{id} jusqu'à status=completed. Renvoie score, tier, findings[], raw_text.
3. Bulk — POST /v1/grounding/batch avec urls[] et optionnellement callback_url. Renvoie batch_id + callback_secret (one-time — sauvegarde-le !).
4. Sitemap — POST /v1/grounding/sitemap-audit avec sitemap_url, optionnellement include_patterns/exclude_patterns. Les crédits sont débités APRÈS le parse.
5. Récupérer les résultats — GET /v1/grounding/batches/{id} (résumé) ou …/results.ndjson (stream ligne par ligne).

Seuils de tier

API

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

Limites connues

• Frameworks eeat + people-first sont des stubs dans la pipeline REST aujourd'hui — v1.5 est le framework qui tourne end-to-end.
• Concurrency par batch non garantie. Concurrency effective = 5 workers côté serveur. Le paramètre concurrency est un hint, pas un contrat.
• Pas d'auto-refund sur les échecs d'audit. Les audits sitemap débitent les crédits APRÈS le parse — tu ne connais pas le nombre exact d'URL avant le filtrage.
• TTL — les résultats expirent en soft après 30 jours, hard-delete après 90. Persiste-les toi-même si tu as besoin d'un historique long terme.

Modules associés

• AI-Visibility Tracking — mesure si tes pages atterrissent vraiment dans les réponses des LLM. Grounding Audit explique pourquoi (ou pas).
• Content Audit — issues SEO classiques. Grounding Audit zoome sur la citation-readiness côté LLM.
• Page Deep Audit — check SEO/performance plus profond par URL.
• Agentic Chat — le master agent peut lancer des grounding audits directement depuis le chat.