API reference / REST v1

Rank & AI visibility

Rank history, local audits, AI Overview evidence, and mention tracking.

All paths below are relative to https://www.agentseo.dev/api/v1. Send your key in x-api-key. Set AGENTSEO_API_KEY in your environment before running the examples. IDs and results are illustrative.

Async result handling · Errors and limits · OpenAPI contract

POST`/audit/local`

Run a local listing audit (AEO starter) for one business/location and return listing readiness plus an agent_workflow action plan.

Request fields · required fields are labeled
Name	Type	Description
`domain`Required	string	Business name or domain (e.g. Cool Creek Family Dental or example.com)
`location`Required	string	Full address or city + state/zip
`language`	string	ISO code (default: en)

POST /audit/local example

curl -X POST https://www.agentseo.dev/api/v1/audit/local?sync=true \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"plumber-nyc.com", "location":"Manhattan, NY"}'

POST`/audit/local/batch`

Queue multiple local audits at once. Utility endpoint for agencies and agent batches. Returns a 202 response with success, message, and a jobs array of queued job IDs.

Request fields · required fields are labeled
Name	Type	Description
`items`Required	array	List of audit objects (max 10)

POST /audit/local/batch example

curl -X POST https://www.agentseo.dev/api/v1/audit/local/batch \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"domain":"a.com","location":"NY"}, {"domain":"b.com","location":"LA"}]}'

POST`/ai-visibility/prompt-set`

Build a stable AI visibility prompt set mapped to platforms, competitors, owned assets, citations, and weekly action routing. Returns prompt buckets, measurement schema, coverage, agent_workflow, and markdown_summary. Requests cost 2 credits and do not run live LLM queries or call a paid search API.

Request fields · required fields are labeled
Name	Type	Description
`target`Required	string	Brand, product, or domain being monitored.
`category`Required	string	Market/category for the prompt set, for example SEO API.
`topics`Required	array	Topic themes that should appear in category, implementation, citation, and asset-gap prompts.
`platforms`	array	chatgpt, perplexity, google_ai, gemini, copilot, or claude.
`owned_assets`	array	Owned URLs with title, page_type, and topics. Used to map prompts back to pages the team can improve.
`competitors`	array	Competitors to include in comparison prompts.
`prompt_count`	integer	Number of prompts to return, 6-50. Default: 20.

POST /ai-visibility/prompt-set example

curl -X POST https://www.agentseo.dev/api/v1/ai-visibility/prompt-set?sync=true \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"AgentSEO","category":"SEO API","audience":"technical marketers","platforms":["chatgpt","perplexity","google_ai"],"competitors":["Semrush API","Ahrefs API"],"topics":["AI visibility monitoring","content QA","SEO workflow automation"],"product_terms":["content brief API","technical QA API"],"personas":["growth marketer","SEO agency owner"],"owned_assets":[{"url":"https://www.agentseo.dev/docs/api-reference","title":"AgentSEO API Reference","page_type":"docs","topics":["content QA","technical QA API","content brief API"]},{"url":"https://www.agentseo.dev/blog/how-to-measure-ai-visibility","title":"How to measure AI visibility","page_type":"blog_post","topics":["AI visibility monitoring"]}],"prompt_count":12,"cadence":"weekly"}'

POST`/ai-overview/extract`

Check whether a query is triggering an AI Overview and return both ai_overview_detected and overview_status, plus a sampled candidate audit, optional target-domain coverage, and an agent_workflow brief.

Request fields · required fields are labeled
Name	Type	Description
`keyword`Required	string	Search query
`location`	string	Geographic location
`location_code`	integer	Optional search location code for deterministic geo-targeting
`language`	string	ISO code (default: en)
`target_domain`	string	Optional domain to check against the sampled candidate set (e.g. linkdoctor.io)

POST /ai-overview/extract example

curl -X POST https://www.agentseo.dev/api/v1/ai-overview/extract?sync=true \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"how to fix a leak", "location":"Austin, TX", "location_code":1026201, "target_domain":"example.com"}'

POST`/rank/track`

Queue a rank tracking job for a specific keyword/URL and return an agent_workflow once the check completes.

Request fields · required fields are labeled
Name	Type	Description
`keyword`Required	string	Target keyword
`url`Required	string	Target URL
`location`	string	Location string
`location_code`	integer	Optional search location code for deterministic geo-targeting

POST /rank/track example

curl -X POST https://www.agentseo.dev/api/v1/rank/track?sync=true \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"seo api", "url":"https://www.agentseo.dev", "location":"Austin, TX", "location_code":1026201}'

GET`/rank/track`

Get rank history for a keyword/URL pair, including agent_workflow summary for the current state.

Query parameters · required fields are labeled
Name	Type	Description
`keyword`Required	string	Target keyword
`url`Required	string	Target URL

GET /rank/track example

curl "https://www.agentseo.dev/api/v1/rank/track?keyword=seo%20api&url=https%3A%2F%2Fwww.agentseo.dev" \
  -H "x-api-key: $AGENTSEO_API_KEY"

POST`/local-visibility/track`

Track local pack visibility across multiple keywords and locations and return an agent_workflow summary.

Request fields · required fields are labeled
Name	Type	Description
`domain`Required	string	Target domain
`keywords`Required	array	List of keywords (max 5)
`locations`Required	array	List of locations (max 3)
`location_codes`	array	Optional search location codes aligned by index with locations
`language`	string	ISO code (default: en)

POST /local-visibility/track example

curl -X POST https://www.agentseo.dev/api/v1/local-visibility/track?sync=true \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com", "keywords":["pizza"], "locations":["Austin, TX"], "location_codes":[1026201]}'

POST`/llm-mentions/track`

Track prompt-set visibility for a brand across sampled discovery surfaces. Returns mention_audit plus agent_workflow so agents can identify weak queries and decide whether to act or keep monitoring.

Request fields · required fields are labeled
Name	Type	Description
`brand`Required	string	Brand name
`queries`Required	array	List of queries to test
`platform`	enum	reddit, twitter, all (default: all)
`limit_per_query`	integer	Max results per query (1-20, default: 8)

POST /llm-mentions/track example

curl -X POST https://www.agentseo.dev/api/v1/llm-mentions/track \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brand":"AgentSEO", "queries":["best seo agents"]}'

← All endpoints

POST/audit/local

POST/audit/local/batch

POST/ai-visibility/prompt-set

POST/ai-overview/extract

POST/rank/track

GET/rank/track

POST/local-visibility/track

POST/llm-mentions/track