GEO Audits

Keep a technical GEO check on a domain or URL and follow it over time. Each audit runs one audit type once, weekly or monthly, keeps every run with its score, findings and issues, compares any two runs and raises alerts when a critical check starts failing, fails again, recovers or the site stops answering. Weekly and monthly runs are available for agent_readiness and robots_txt; the other types run once and return a score only. Manual runs are limited to 6 per audit per rolling hour and 200 per account per day, and active recurring audits are capped per plan. Writes need a read_write scope API key and, for team members, the matching permission on GEO Optimization.

GET/geo_audits

List the project's audits, most recently updated first, with the latest run, open issue counts and next scheduled run. Archived audits are left out unless status=archived. recurring_available says whether the type can run weekly or monthly, and checks_tracked whether its runs produce findings and issues or a score only.

Params:
  • project_idrequired
  • audit_typeagent_readiness, robots_txt, crawlability, schema, content_readiness, discoverability, site_structure
  • statusactive, paused, archived
  • cadenceonce, weekly, monthly
  • page
  • per_pagemaximum 100

POST/geo_audits

Create one audit per entry of audit_types for a domain or URL. Each audit starts its first run at once, and that run counts against the manual run limits. cadence weekly or monthly is accepted only for agent_readiness and robots_txt and counts against the plan limit of active recurring audits (ERR_LIMIT_REACHED). Creating an audit that was archived restores it with its history. Requires a read_write scope API key.

Body (JSON):
  • project_idrequired
  • targetrequired, the domain or page URL
  • audit_typesrequired array: agent_readiness, robots_txt, crawlability, schema, content_readiness, discoverability, site_structure
  • cadenceoptional: once, weekly, monthly; default once

GET/geo_audits/:id

One audit with its schedule, status, latest run and open issue counts. paused_reason is user, or unreachable when three runs in a row could not reach the site.

Params:
  • project_idrequired
  • idin the URL, the audit id

PATCH/geo_audits/:id

Change the cadence, the schedule day and hour, the email alerts or the status of an audit. status paused stops scheduled runs, active resumes them and archived is the same as DELETE. Making an audit recurring or resuming it counts against the plan limit of active recurring audits (ERR_LIMIT_REACHED). Requires a read_write scope API key and, for team members, update permission on GEO Optimization.

Body (JSON):
  • project_idrequired
  • cadenceoptional: once, weekly, monthly
  • schedule_dayoptional: 0 Sunday to 6 for weekly, 1 to 28 for monthly
  • schedule_houroptional, 0 to 23 in the audit time zone
  • statusoptional: active, paused, archived
  • email_alertsoptional boolean
  • idin the URL, the audit id

DELETE/geo_audits/:id

Archive an audit. It stops running and leaves the list (list it with status=archived), and creating the same audit again restores it with its history. Requires a read_write scope API key and, for team members, delete permission on GEO Optimization.

Params:
  • project_idrequired
  • idin the URL, the audit id

GET/geo_audits/:id/comparison

Compare two completed runs of an audit check by check. Defaults to the latest completed run against the one before it. changes lists every check and subject with its change (new, fixed, changed, appeared, disappeared, unchanged), counts totals them, and score_delta and metric_deltas give the movement. comparable: false means the checks or the audit settings changed between the two runs. Returns ERR_NOT_FOUND when the audit has no completed run yet.

Params:
  • project_idrequired
  • from_runoptional run number
  • to_runoptional run number
  • idin the URL, the audit id

GET/geo_audits/:geo_audit_id/runs

The runs of an audit, newest first, with score, grade, status, trigger (scheduled, manual, api, mcp) and the new, fixed and regressed issue counts each run produced. Also available as flat or CSV output.

Params:
  • project_idrequired
  • page
  • per_pagemaximum 100
  • outputoptional: flat, csv
  • geo_audit_idin the URL

POST/geo_audits/:geo_audit_id/runs

Start a manual run and get it back with status queued, then poll the run until its status is completed, failed or unreachable. Limited to 6 manual runs per audit per rolling hour and 200 per account per day (ERR_LIMIT_REACHED); scheduled runs do not count. Requires a read_write scope API key.

Params:
  • project_idrequired
  • geo_audit_idin the URL

GET/geo_audits/:geo_audit_id/runs/:sequence

One run with its score, metrics and full result_data, the report of the run in the shape of the matching Technical GEO report type. result_data is null until the run completes; a failed or unreachable run explains why in error.

Params:
  • project_idrequired
  • geo_audit_idin the URL
  • sequencein the URL, the run number

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

The findings of one run, most severe first: one row per check and subject (site for site-wide checks, a bot for robots.txt bot checks) with its status (pass, warn, fail, info, not_applicable, unknown), severity and evidence. Only agent_readiness and robots_txt runs produce findings. Also available as flat or CSV output.

Params:
  • project_idrequired
  • page
  • per_pagemaximum 100
  • outputoptional: flat, csv
  • geo_audit_idin the URL
  • sequencein the URL, the run number

GET/geo_audits/:geo_audit_id/issues

The issues of an audit across its runs, most severe first. An issue is a failing check and subject followed from run to run: state is open, fixed or gone, badge says how the latest comparable run moved it (new, persisting, regressed, fixed, gone), and accepted marks issues accepted on purpose.

Params:
  • project_idrequired
  • stateoptional: open, accepted, fixed, gone; open leaves out accepted issues; default all
  • page
  • per_pagemaximum 100
  • geo_audit_idin the URL

PATCH/geo_audits/:geo_audit_id/issues/:id

Accept an issue or reopen it. An accepted issue stays listed but leaves the open count, and the acceptance lapses on its own when the issue's evidence changes. Requires a read_write scope API key and, for team members, update permission on GEO Optimization.

Body (JSON):
  • project_idrequired
  • acceptedrequired, true accepts and false reopens
  • geo_audit_idin the URL
  • idin the URL, the issue id

GET/geo_alerts

Alerts raised by the project's GEO audits, newest first. Each alert belongs to one run and lists its events: new_critical (a critical check now fails), regression (a fixed check fails again), recovered, score_drop, unreachable and paused (three runs in a row could not reach the site). Each event carries a readable message.

Params:
  • project_idrequired
  • audit_idoptional, only alerts of this audit
  • page
  • per_pagemaximum 100