Audits GEO
Surveillez un domaine ou une URL avec un contrôle GEO technique et suivez son évolution. Chaque audit exécute un type d’audit (une fois, chaque semaine ou chaque mois), conserve chaque exécution avec son score, ses constats et ses problèmes, compare deux exécutions au choix et déclenche des alertes lorsqu’un contrôle critique commence à échouer, échoue de nouveau, se rétablit ou lorsque le site cesse de répondre. Les exécutions hebdomadaires et mensuelles sont disponibles pour agent_readiness et robots_txt ; les autres types s’exécutent une seule fois et ne renvoient qu’un score. Les exécutions manuelles sont limitées à 6 par audit sur une heure glissante et à 200 par compte et par jour, et le nombre d’audits récurrents actifs est plafonné selon le forfait. Les écritures nécessitent une clé API de portée read_write et, pour les membres de l’équipe, l’autorisation correspondante sur les audits GEO.
GET/geo_audits
Liste les audits du projet, du plus récemment mis à jour au plus ancien, avec la dernière exécution, le nombre de problèmes ouverts et la prochaine exécution programmée. Les audits archivés sont exclus, sauf avec status=archived. recurring_available indique si le type peut s’exécuter chaque semaine ou chaque mois, et checks_tracked si ses exécutions produisent des constats et des problèmes ou seulement un score.
project_idobligatoireaudit_typeagent_readiness, robots_txt, crawlability, schema, content_readiness, discoverability, site_structurestatusactive, paused, archivedcadenceonce, weekly, monthlypageper_page100 au maximum
POST/geo_audits
Crée un audit par entrée de audit_types pour un domaine ou une URL. Chaque audit lance aussitôt sa première exécution, qui est décomptée des limites d’exécutions manuelles. La valeur weekly ou monthly de cadence n’est acceptée que pour agent_readiness et robots_txt, et elle est décomptée de la limite d’audits récurrents actifs du forfait (ERR_LIMIT_REACHED). Créer un audit qui avait été archivé le restaure avec son historique. Nécessite une clé API de portée read_write.
project_idobligatoiretargetobligatoire, le domaine ou l’URL de la pageaudit_typestableau obligatoire : agent_readiness, robots_txt, crawlability, schema, content_readiness, discoverability, site_structurecadencefacultatif : once, weekly, monthly ; once par défaut
GET/geo_audits/:id
Un audit avec sa programmation, son statut, sa dernière exécution et le nombre de problèmes ouverts. paused_reason vaut user, unreachable lorsque trois exécutions consécutives n’ont pas pu joindre le site, ou quota lorsque le compte a plus d’audits récurrents actifs que son forfait ne le permet.
project_idobligatoireiddans l’URL, l’identifiant de l’audit
PATCH/geo_audits/:id
Modifie la fréquence, le jour et l’heure de programmation, les alertes par e-mail ou le statut d’un audit. Pour status, paused suspend les exécutions programmées, active les reprend et archived équivaut à DELETE. Un audit rendu récurrent ou réactivé est décompté de la limite d’audits récurrents actifs du forfait (ERR_LIMIT_REACHED). Nécessite une clé API de portée read_write et, pour les membres de l’équipe, l’autorisation de modification sur les audits GEO.
- Corps (JSON) :
project_id(obligatoire),cadence(facultatif : once, weekly, monthly),schedule_day(facultatif : de 0 (dimanche) à 6 pour weekly, de 1 à 28 pour monthly),schedule_hour(facultatif, de 0 à 23 dans le fuseau horaire de l’audit),status(facultatif : active, paused, archived),email_alerts(booléen facultatif),id(dans l’URL, l’identifiant de l’audit).
DELETE/geo_audits/:id
Archive un audit. Il cesse de s’exécuter et sort de la liste (pour le lister, utilisez status=archived). Recréer le même audit le restaure avec son historique. Nécessite une clé API de portée read_write et, pour les membres de l’équipe, l’autorisation de suppression sur les audits GEO.
project_idobligatoireiddans l’URL, l’identifiant de l’audit
GET/geo_audits/:id/comparison
Compare deux exécutions terminées d’un audit, contrôle par contrôle. Par défaut, compare la dernière exécution terminée à la précédente. changes liste chaque contrôle et chaque sujet avec son change (new, fixed, changed, appeared, disappeared, unchanged), counts en fait le total, et score_delta et metric_deltas donnent l’évolution. comparable: false signifie que les contrôles ou les paramètres de l’audit ont changé entre les deux exécutions. Renvoie ERR_NOT_FOUND si l’audit n’a encore aucune exécution terminée.
project_idobligatoirefrom_runnuméro d’exécution, facultatifto_runnuméro d’exécution, facultatifiddans l’URL, l’identifiant de l’audit
GET/geo_audits/:geo_audit_id/runs
Les exécutions d’un audit, de la plus récente à la plus ancienne, avec score, note, statut, déclencheur (scheduled, manual, api, mcp) et le nombre de problèmes nouveaux, corrigés et réapparus relevés par chaque exécution. Également disponible au format à plat ou CSV.
project_idobligatoirepageper_page100 au maximumoutputfacultatif : flat, csvgeo_audit_iddans l’URL
POST/geo_audits/:geo_audit_id/runs
Lance une exécution manuelle et la renvoie avec le statut queued. Interrogez ensuite l’exécution jusqu’à ce que son statut soit completed, failed ou unreachable. Les exécutions manuelles sont limitées à 6 par audit sur une heure glissante et à 200 par compte et par jour (ERR_LIMIT_REACHED) ; les exécutions programmées ne sont pas décomptées. Nécessite une clé API de portée read_write.
project_idobligatoiregeo_audit_iddans l’URL
GET/geo_audits/:geo_audit_id/runs/:sequence
Une exécution avec son score, ses metrics et l’intégralité de result_data, le rapport de l’exécution au format du type de rapport GEO technique correspondant. result_data vaut null tant que l’exécution n’est pas terminée ; une exécution en échec ou dont le site était injoignable en donne la raison dans error.
project_idobligatoiregeo_audit_iddans l’URLsequencedans l’URL, le numéro d’exécution
GET/geo_audits/:geo_audit_id/runs/:sequence/findings
Les constats d’une exécution, du plus grave au moins grave : une ligne par contrôle et par sujet (site pour les contrôles portant sur tout le site, un bot pour les contrôles de bots du robots.txt), avec les champs status (pass, warn, fail, info, not_applicable, unknown), severity et evidence. Seules les exécutions agent_readiness et robots_txt produisent des constats. Également disponible au format à plat ou CSV.
project_idobligatoirepageper_page100 au maximumoutputfacultatif : flat, csvgeo_audit_iddans l’URLsequencedans l’URL, le numéro d’exécution
GET/geo_audits/:geo_audit_id/issues
Les problèmes d’un audit sur l’ensemble de ses exécutions, du plus grave au moins grave. Un problème est un contrôle en échec sur un sujet, suivi d’une exécution à l’autre : state vaut open, fixed ou gone, badge indique comment la dernière exécution comparable l’a fait évoluer (new, persisting, regressed, fixed, gone) et accepted signale les problèmes acceptés délibérément.
project_idobligatoirestatefacultatif : open, accepted, fixed, gone ; open exclut les problèmes acceptés ; tous par défautpageper_page100 au maximumgeo_audit_iddans l’URL
PATCH/geo_audits/:geo_audit_id/issues/:id
Accepte un problème ou le rouvre. Un problème accepté reste listé mais sort du décompte des problèmes ouverts, et l’acceptation devient caduque d’elle-même lorsque les éléments de preuve du problème changent. Nécessite une clé API de portée read_write et, pour les membres de l’équipe, l’autorisation de modification sur les audits GEO.
project_idobligatoireacceptedobligatoire, true pour accepter et false pour rouvrirgeo_audit_iddans l’URLiddans l’URL, l’identifiant du problème
GET/geo_alerts
Alertes déclenchées par les audits GEO du projet, des plus récentes aux plus anciennes. Chaque alerte appartient à une exécution et liste ses events : new_critical (un contrôle critique échoue désormais), regression (un contrôle corrigé échoue de nouveau), recovered, score_drop, unreachable et paused (trois exécutions consécutives n’ont pas pu joindre le site). Chaque événement comporte un message lisible.
project_idobligatoireaudit_idfacultatif, uniquement les alertes de cet auditpageper_page100 au maximum