Skip to main content

Agent GEO API Documentation

Authentication​

All endpoints in this section require an API key.

Use either header:

  • x-api-key: <api-key>
  • Authorization: Bearer <api-key>

Where to find your API key​

The x-api-key used to authenticate GEO/AEO requests is available on your Agent Settings page under API Keys. Locate the agent you want to use, reveal the key value, and copy it into your request header.

Example header:

  • x-api-key: <api-key-from-agent-settings>

Screenshot: Agent Settings → API Keys

Agent Settings - API Keys

Common Error Responses​

The GEO API routes can return these common errors:

  • 401 Unauthorized: Missing API key, invalid API key, or project mapping failed.
  • 403 Forbidden: API key inactive, or GEO subscription/plan requirement not met.
  • 429 Too Many Requests: Rate limit exceeded.
  • 500 Internal Server Error: Unexpected server error.

GET: Retrieve GEO Reports​

Description​

This route retrieves management GEO reports by report type for the authenticated API key context.

Method​

GET

URL​

/api/geo/reports

Query Parameters​

  • type (string, required):
    • analytics
    • url-analysis
    • keyword-expansion
    • social-brand-audit
    • agent-readiness
    • trend
    • site-wide
    • action-plan
    • citation-monitor
    • prospect-snapshot
  • page (number, optional): Page number. Default: 1. Maximum effective page: 1000.
  • limit (number, optional): Page size. Default: 20. Maximum: 100.
  • from (string, optional): Start datetime/date filter (ISO).
  • to (string, optional): End datetime/date filter (ISO).

Response​

  • Returns a JSON payload containing paginated report data for the selected report type.

Status Codes​

  • 200 OK: Reports retrieved successfully.
  • 400 Bad Request: Invalid type.
  • 500 Internal Server Error: Error listing reports.

Throws​

  • An error if authentication, validation, or report retrieval fails.

Example cURL​

curl --location 'https://app.ai12z.net/api/geo/reports?type=analytics&page=1&limit=10&from=2026-07-01&to=2026-07-31' \
--header 'x-api-key: <YOUR_KEY>'

GET: Retrieve GEO Report By Id​

Description​

This route retrieves a single management GEO report by ID.

Method​

GET

URL Parameters​

  • id (string): The GEO report ID.

URL​

/api/geo/reports/{id}

Response​

  • Returns a JSON payload with the report and inferred report type.

Status Codes​

  • 200 OK: Report retrieved successfully.
  • 404 Not Found: Report not found.
  • 500 Internal Server Error: Error retrieving report.

Throws​

  • An error if authentication or report retrieval fails.

Example cURL​

curl --location 'https://app.ai12z.net/api/geo/reports/{id}' \
--header 'Authorization: Bearer <YOUR_KEY>'

GET: Retrieve GEO Dashboard​

Description​

This route retrieves an aggregate GEO dashboard payload, including key scores and latest reports across GEO report categories.

Method​

GET

URL​

/api/geo/dashboard

Query Parameters​

  • from (string, optional): Start datetime/date filter (ISO).
  • to (string, optional): End datetime/date filter (ISO).

Response​

  • Returns a JSON payload including:
    • projectId
    • orgId
    • generatedAt
    • range
    • scores
    • latestReports

Status Codes​

  • 200 OK: Dashboard retrieved successfully.
  • 500 Internal Server Error: Error retrieving dashboard.

Throws​

  • An error if authentication or dashboard retrieval fails.

Example cURL​

curl --location 'https://app.ai12z.net/api/geo/dashboard?from=2026-07-01T00:00:00.000Z&to=2026-07-31T23:59:59.999Z' \
--header 'x-api-key: <YOUR_KEY>'

GET: Retrieve In-Progress GEO Job Count​

Description​

This route returns the count of GEO jobs currently in IN_PROGRESS or queued state for the authenticated API key context.

Method​

GET

URL​

/api/geo/jobs/in-progress-count

Query Parameters​

  • type (string, optional): One job type or a comma-separated list.
  • types (string[], optional): Repeated query parameter for multiple job types.

Allowed type values:

  • analytics
  • url-analysis
  • keyword-expansion
  • social-brand-audit
  • agent-readiness
  • trend
  • site-wide
  • action-plan
  • citation-monitor
  • prospect-snapshot

Response​

  • Returns JSON in this shape:
{
  "count": 3
}

Status Codes​

  • 200 OK: Count retrieved successfully.
  • 400 Bad Request: Invalid type filter.
  • 500 Internal Server Error: Error retrieving job count.

Throws​

  • An error if authentication, validation, or count query fails.

Example cURL​

curl --location --get 'https://app.ai12z.net/api/geo/jobs/in-progress-count' \
--header 'x-api-key: <YOUR_KEY>' \
--data-urlencode 'type=analytics,trend,citation-monitor'
curl --location --get 'https://app.ai12z.net/api/geo/jobs/in-progress-count' \
--header 'x-api-key: <YOUR_KEY>' \
--data-urlencode 'types=analytics' \
--data-urlencode 'types=trend' \
--data-urlencode 'types=citation-monitor'
Last updated on