Auditorías GEO

Mantén una comprobación GEO técnica sobre un dominio o una URL y sigue su evolución. Cada auditoría ejecuta un tipo de auditoría una vez, de forma semanal o mensual, conserva todas las ejecuciones con su puntuación, resultados e incidencias, compara dos ejecuciones cualesquiera y genera alertas cuando una comprobación crítica empieza a fallar, vuelve a fallar, se recupera o el sitio deja de responder. Las ejecuciones semanales y mensuales están disponibles para agent_readiness y robots_txt; los demás tipos se ejecutan una sola vez y solo devuelven una puntuación. Las ejecuciones manuales están limitadas a 6 por auditoría y hora (ventana móvil) y a 200 por cuenta y día, y las auditorías recurrentes activas tienen un tope según el plan. Las operaciones de escritura requieren una clave de API con el ámbito read_write y, para los miembros del equipo, el permiso correspondiente en Optimización GEO.

GET/geo_audits

Lista las auditorías del proyecto, de la actualizada más recientemente a la más antigua, con la última ejecución, el número de incidencias abiertas y la próxima ejecución programada. Las auditorías archivadas no aparecen salvo que uses status=archived. recurring_available indica si el tipo puede ejecutarse cada semana o cada mes, y checks_tracked si sus ejecuciones generan resultados e incidencias o solo una puntuación.

Parámetros:
  • project_idobligatorio
  • audit_typeagent_readiness, robots_txt, crawlability, schema, content_readiness, discoverability, site_structure
  • statusactive, paused, archived
  • cadenceonce, weekly, monthly
  • page
  • per_pagemáximo 100

POST/geo_audits

Crea una auditoría por cada elemento de audit_types para un dominio o una URL. Cada auditoría inicia su primera ejecución de inmediato, y esa ejecución cuenta para los límites de ejecuciones manuales. cadence con weekly o monthly solo se admite para agent_readiness y robots_txt y cuenta para el límite del plan de auditorías recurrentes activas (ERR_LIMIT_REACHED). Si creas una auditoría que estaba archivada, se restaura con su historial. Requiere una clave de API con el ámbito read_write.

Cuerpo (JSON):
  • project_idobligatorio
  • targetobligatorio, el dominio o la URL de la página
  • audit_typesobligatorio, array: agent_readiness, robots_txt, crawlability, schema, content_readiness, discoverability, site_structure
  • cadenceopcional: once, weekly, monthly; por defecto once

GET/geo_audits/:id

Una auditoría con su programación, estado, última ejecución y número de incidencias abiertas. paused_reason es user, o unreachable cuando tres ejecuciones seguidas no pudieron acceder al sitio.

Parámetros:
  • project_idobligatorio
  • iden la URL, el identificador de la auditoría

PATCH/geo_audits/:id

Cambia la cadencia, el día y la hora de programación, las alertas por correo o el estado de una auditoría. Con status, paused detiene las ejecuciones programadas, active las reanuda y archived equivale a DELETE. Hacer recurrente una auditoría o reanudarla cuenta para el límite del plan de auditorías recurrentes activas (ERR_LIMIT_REACHED). Requiere una clave de API con el ámbito read_write y, para los miembros del equipo, permiso de edición en Optimización GEO.

Cuerpo (JSON):
  • project_idobligatorio
  • cadenceopcional: once, weekly, monthly
  • schedule_dayopcional: de 0 para domingo a 6 en semanal, de 1 a 28 en mensual
  • schedule_houropcional, de 0 a 23 en la zona horaria de la auditoría
  • statusopcional: active, paused, archived
  • email_alertsopcional, booleano
  • iden la URL, el identificador de la auditoría

DELETE/geo_audits/:id

Archiva una auditoría. Deja de ejecutarse y desaparece de la lista (puedes consultarla con status=archived), y si vuelves a crear la misma auditoría se restaura con su historial. Requiere una clave de API con el ámbito read_write y, en el caso de los miembros del equipo, permiso de eliminación en Optimización GEO.

Parámetros:
  • project_idobligatorio
  • iden la URL, el id de la auditoría

GET/geo_audits/:id/comparison

Compara, comprobación a comprobación, dos ejecuciones completadas de una auditoría. Por defecto compara la última ejecución completada con la anterior. changes enumera cada comprobación y elemento con su change (new, fixed, changed, appeared, disappeared, unchanged), counts los totaliza, y score_delta y metric_deltas indican la variación. comparable: false significa que las comprobaciones o los ajustes de la auditoría cambiaron entre las dos ejecuciones. Devuelve ERR_NOT_FOUND cuando la auditoría todavía no tiene ninguna ejecución completada.

Parámetros:
  • project_idobligatorio
  • from_runopcional, número de ejecución
  • to_runopcional, número de ejecución
  • iden la URL, el identificador de la auditoría

GET/geo_audits/:geo_audit_id/runs

Las ejecuciones de una auditoría, de la más reciente a la más antigua, con su puntuación, nota, estado, origen (scheduled, manual, api, mcp) y el número de incidencias nuevas, corregidas y reaparecidas que produjo cada ejecución. También disponible en formato plano o CSV.

Parámetros:
  • project_idobligatorio
  • page
  • per_pagemáximo 100
  • outputopcional: flat, csv
  • geo_audit_iden la URL

POST/geo_audits/:geo_audit_id/runs

Inicia una ejecución manual y te la devuelve con el estado queued; después consulta la ejecución hasta que su estado sea completed, failed o unreachable. Hay un límite de 6 ejecuciones manuales por auditoría en una hora móvil y de 200 por cuenta al día (ERR_LIMIT_REACHED); las ejecuciones programadas no cuentan. Requiere una clave de API con el alcance read_write.

Parámetros:
  • project_idobligatorio
  • geo_audit_iden la URL

GET/geo_audits/:geo_audit_id/runs/:sequence

Una ejecución con su puntuación, metrics y el result_data completo, el informe de la ejecución con el formato del tipo de informe GEO técnico correspondiente. result_data es null hasta que la ejecución termina; si una ejecución falla o no se puede alcanzar, el motivo aparece en error.

Parámetros:
  • project_idobligatorio
  • geo_audit_iden la URL
  • sequenceen la URL, el número de ejecución

GET/geo_audits/:geo_audit_id/runs/:sequence/findings

Los resultados de una ejecución, de mayor a menor gravedad: una fila por comprobación y elemento (site para las comprobaciones de todo el sitio, un bot para las comprobaciones de bots de robots.txt) con su status (pass, warn, fail, info, not_applicable, unknown), severity y evidence. Solo las ejecuciones de agent_readiness y robots_txt generan resultados. También disponible en formato plano o CSV.

Parámetros:
  • project_idobligatorio
  • page
  • per_pagemáximo 100
  • outputopcional: flat, csv
  • geo_audit_iden la URL
  • sequenceen la URL, el número de ejecución

GET/geo_audits/:geo_audit_id/issues

Las incidencias de una auditoría a lo largo de sus ejecuciones, de mayor a menor gravedad. Una incidencia es una comprobación fallida sobre un elemento concreto, a la que se da seguimiento de una ejecución a otra: state es open, fixed o gone, badge indica cómo la ha movido la última ejecución comparable (new, persisting, regressed, fixed, gone) y accepted marca las incidencias aceptadas a propósito.

Parámetros:
  • project_idobligatorio
  • stateopcional: open, accepted, fixed, gone; open excluye las incidencias aceptadas; por defecto, todas
  • page
  • per_pagemáximo 100
  • geo_audit_iden la URL

PATCH/geo_audits/:geo_audit_id/issues/:id

Acepta una incidencia o la vuelve a abrir. Una incidencia aceptada sigue apareciendo en el listado, pero deja de contar como abierta, y la aceptación caduca por sí sola cuando cambian las pruebas de la incidencia. Requiere una clave de API con el alcance read_write y, para los miembros del equipo, permiso de edición en Optimización GEO.

Cuerpo (JSON):
  • project_idobligatorio
  • acceptedobligatorio, true acepta y false reabre
  • geo_audit_iden la URL
  • iden la URL, el identificador de la incidencia

GET/geo_alerts

Alertas generadas por las auditorías GEO del proyecto, de la más reciente a la más antigua. Cada alerta pertenece a una ejecución y enumera sus events: new_critical (una comprobación crítica falla ahora), regression (una comprobación corregida vuelve a fallar), recovered, score_drop, unreachable y paused (tres ejecuciones seguidas no pudieron acceder al sitio). Cada evento incluye un message legible.

Parámetros:
  • project_idobligatorio
  • audit_idopcional, solo las alertas de esta auditoría
  • page
  • per_pagemáximo 100