---
title: "Create GEO audits"
method: POST
path: "/geo_audits"
tags: ["GEO Audits"]
---

# Create GEO audits

`POST /geo_audits`

## Request

- Base URL: `https://api.llmpulse.ai/api/v1`
- URL: `https://api.llmpulse.ai/api/v1/geo_audits`
- Auth: API key in header `Authorization`

Creates one audit per entry of audit_types and starts the first run of each (it counts against the manual run limits: 6 per audit per hour, 200 per account per day). cadence weekly or monthly is accepted only for types whose checks are tracked run to run, 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.

## Request body

- GeoAuditCreateRequest
  - `project_id` integer, required
  - `target` string, required: The domain (site-wide types) or page URL to audit
  - `audit_types` string[], required: One or more audit types; each becomes its own audit and starts its first run
  - `cadence` 'once' | 'weekly' | 'monthly': once (default), weekly or monthly. Weekly and monthly need a type whose checks are tracked and count against the plan limit of recurring audits

## Response `201`

The created audits

- GeoAuditCreateResponse
  - `project_id` integer
  - `data` GeoAudit[]
    - `id` string: Stable audit id
    - `audit_type` 'agent_readiness' | 'robots_txt' | 'crawlability' | 'schema' | 'content_readiness' | 'discoverability' | 'site_structure'
    - `target` string: The audited domain (site-wide types) or page URL, normalized
    - `country_code` string, nullable
    - `cadence` 'once' | 'weekly' | 'monthly'
    - `status` 'active' | 'paused' | 'archived'
    - `paused_reason` string, nullable: Null unless status is paused. user (paused by hand), unreachable (three runs in a row could not reach the site) or quota (the account has more active recurring audits than its plan allows; resume it once there is room)
    - `schedule` GeoAuditSchedule, nullable: Present for weekly and monthly audits. day is 0 (Sunday) to 6 for weekly audits and 1 to 28 for monthly ones; hour is in timezone.
      - `day` integer
      - `hour` integer
      - `timezone` string
    - `next_run_at` string, date-time, nullable
    - `email_alerts` boolean
    - `recurring_available` boolean: Whether this audit type can run weekly or monthly
    - `checks_tracked` boolean: Whether runs of this type produce findings and issues, or a score only
    - `latest_run` GeoAuditRun, nullable: One run of an audit. Null where an audit has no run yet (latest_run) or a comparison has no earlier run (from_run).
      - `sequence` integer: Run number within the audit, starting at 1
      - `status` 'queued' | 'running' | 'completed' | 'failed' | 'unreachable'
      - `trigger` 'scheduled' | 'manual' | 'api' | 'mcp' | 'legacy_import'
      - `score` number, nullable
      - `grade` string, nullable
      - `score_delta` number, nullable: Score change against the previous completed run
      - `comparable_to_previous` boolean: False when the checks or the audit settings changed since the previous run, so a diff may reflect that change
      - `new_issues` integer
      - `fixed_issues` integer
      - `regressed_issues` integer
      - `error` string, nullable
      - `engine_version` string, nullable
      - `created_at` string, date-time
      - `finished_at` string, date-time, nullable
      - `app_url` string
    - `open_issues` integer
    - `open_critical_issues` integer
    - `created_at` string, date-time
    - `app_url` string
  - `request_id` string

## Other responses

- `403`: API key lacks write permission
- `422`: Invalid parameters

## Changes

- **2026-10-09** `61976d9236d8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/llmpulse/apis/llm-pulse-api/changes/geo_audits/post.md)

---

[API](https://skmtc.dev/llmpulse/apis/llm-pulse-api.md) - [All operations](https://skmtc.dev/llmpulse/apis/llm-pulse-api/llms.txt) - [OpenAPI document](https://skmtc.dev/llmpulse/apis/llm-pulse-api/revisions/38a31f123641?raw)