Documentation

API Reference

Workflow POST endpoints are usually async-first. Utility and system endpoints such as /extract , /webhooks/endpoints , and /webhooks/deliveries/{id}/retry are synchronous. Use ?sync=true on supported endpoints to open a short inline processing window. If a result is not ready yet, the API returns 202 with a job payload you can poll.

Most queued workflow endpoints return a standard async envelope with poll_url, events_url, and retry_after_seconds. The main exception is /audit/local/batch, which returns an array of queued job IDs instead of one pollable job envelope.

Async Flow

Queue work with any async endpoint, then use the returned poll_url, events_url, and retry_after_seconds fields from the queued payload. You can also poll /jobs/{id} or stream /jobs/{id}/events.

Deterministic Geo

Geo-targeted endpoints accept human-friendly location and optional location_code. If both are provided, location_code wins.

Local Audit Input

domain on /audit/local can be a business name or a domain.

Agent Workflow Block

Core workflow endpoints include agent_workflow with a decision, confidence, recommended actions, evidence, limitations, and next calls for downstream agents.

Request Attribution

Optional x-project-id and x-workflow-id headers are stored on usage logs and async jobs. The official SDK, OpenClaw plugin, and MCP surfaces can set these defaults once for you. Polling /jobs/{id} returns the same context back.

Core Workflows

POST/audit/local

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

Parameters

Name	Type	Description
domain *	string	Business name or domain (e.g. Cool Creek Family Dental or example.com)
location *	string	Full address or city + state/zip
language	string	ISO code (default: en)

Example

curl -X POST https://www.agentseo.dev/api/v1/audit/local?sync=true \
  -H "x-api-key: sk_live_..." \
  -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.

Parameters

Name	Type	Description
items *	array	List of audit objects (max 10)

Example

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

POST/content/gap

Identify missing topics and return an agent_workflow plus a compact content_brief for what to publish or refresh next.

Parameters

Name	Type	Description
url *	string	Your target URL
keyword *	string	Main target keyword
location	string	Target location (default: US)
location_code	integer	Optional DataForSEO location code for deterministic geo-targeting
language	string	ISO code (default: en)
scrape_depth	enum	h1, h2, or h3 (default: h3)

Example

curl -X POST https://www.agentseo.dev/api/v1/content/gap?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://mysite.com/blog/seo", "keyword":"seo tips", "location":"Austin, TX", "location_code":1026201}'

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.

Parameters

Name	Type	Description
keyword *	string	Search query
location	string	Geographic location
location_code	integer	Optional DataForSEO 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)

Example

curl -X POST https://www.agentseo.dev/api/v1/ai-overview/extract?sync=true \
  -H "x-api-key: sk_live_..." \
  -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.

Parameters

Name	Type	Description
keyword *	string	Target keyword
url *	string	Target URL
location	string	Location string
location_code	integer	Optional DataForSEO location code for deterministic geo-targeting

Example

curl -X POST https://www.agentseo.dev/api/v1/rank/track?sync=true \
  -H "x-api-key: sk_live_..." \
  -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.

Parameters

Name	Type	Description
keyword *	string	Target keyword
url *	string	Target URL

Example

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

POST/local-visibility/track

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

Parameters

Name	Type	Description
domain *	string	Target domain
keywords *	array	List of keywords (max 5)
locations *	array	List of locations (max 3)
location_codes	array	Optional DataForSEO location codes aligned by index with locations
language	string	ISO code (default: en)

Example

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

Supporting Primitives

POST/search

Perform a Google search with optional domain filtering. Returns raw SERP evidence plus agent_support so an agent can choose the next workflow.

Parameters

Name	Type	Description
query *	string	Search query
location	string	Target location (default: United States)
location_code	integer	Optional DataForSEO location code for deterministic geo-targeting
language	string	ISO code (default: en)
limit	integer	Max results (1-50, default: 10)
include_domains	array	Only return results from these domains
exclude_domains	array	Exclude results from these domains

Example

curl -X POST https://www.agentseo.dev/api/v1/search?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"query":"best crm software", "location":"Austin, TX", "location_code":1026201, "limit":5}'

POST/extract

Extract clean content (markdown/text/html) from any URL. Returns page metadata, structural headings, and agent_support for follow-up workflow selection.

Parameters

Name	Type	Description
url *	string	Target URL
format	enum	markdown, text, html (default: markdown)
include_images	boolean	Include image extraction (default: false)

Example

curl -X POST https://www.agentseo.dev/api/v1/extract \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://tcrn.ch/example"}'

POST/analyze/serp

Analyze SERP features (Local Pack, AI Overview, Shopping) for a keyword. Returns serp_opportunity so agents can infer intent, competition, and the right content format.

Parameters

Name	Type	Description
keyword *	string	Target keyword
location	string	Target location (default: US)
location_code	integer	Optional DataForSEO location code for deterministic geo-targeting
device	enum	desktop or mobile (default: desktop)
language	string	ISO code (default: en)

Example

curl -X POST https://www.agentseo.dev/api/v1/analyze/serp?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"keyword":"plumbers near me", "location":"Austin, TX", "location_code":1026201, "device":"mobile"}'

Experimental Workflows

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.

Parameters

Name	Type	Description
brand *	string	Brand name
queries *	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)

Example

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

POST/content-decay/detect

Identify content that is losing ranking momentum over time. Returns decay_audit plus agent_workflow so agents can judge urgency, likely cause, and the right next investigation.

Parameters

Name	Type	Description
url *	string	Page URL to check
keyword *	string	Main keyword
lookback_days	integer	Days to analyze (3-180, default: 30)
threshold	number	Decay threshold % (default: 3)

Example

curl -X POST https://www.agentseo.dev/api/v1/content-decay/detect?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/blog/old-post", "keyword":"legacy keyword"}'

POST/keyword-cluster/build

Group keywords into intent-led clusters and return cluster_plan plus agent_workflow so agents can map cluster targets to the right page types before publishing.

Parameters

Name	Type	Description
keywords *	array	List of keywords (max 200)

Example

curl -X POST https://www.agentseo.dev/api/v1/keyword-cluster/build?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"keywords":["best shoes", "running shoes", "cheap sneakers"]}'

POST/social/listen

Find web discussion evidence for a topic and return insights plus agent_workflow. This is web-wide discovery for pain points and buying signals, not native platform monitoring.

Parameters

Name	Type	Description
query *	string	Topic or keyword
platform	enum	reddit, twitter, all (default: all)
limit	integer	Max results (1-50, default: 10)

Example

curl -X POST https://www.agentseo.dev/api/v1/social/listen?sync=true \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"query":"agentic seo", "platform":"reddit"}'

System

GET/webhooks/endpoints

List the webhook endpoints registered for your workspace.

Example

curl https://www.agentseo.dev/api/v1/webhooks/endpoints \
  -H "x-api-key: sk_live_..."

POST/webhooks/endpoints

Create a signed webhook endpoint for async job delivery. The signing secret is returned once on create.

Parameters

Name	Type	Description
url *	string	HTTPS endpoint that will receive webhook POSTs
events	array	Any of job.completed, job.failed, project.budget_warning, or project.budget_exceeded

Example

curl -X POST https://www.agentseo.dev/api/v1/webhooks/endpoints \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/agentseo","events":["job.completed","project.budget_warning","project.budget_exceeded"]}'

PATCH/webhooks/endpoints/{id}

Update a webhook endpoint in place. Use this to rotate target URLs, event subscriptions, descriptions, or to pause delivery with is_active=false.

Parameters

Name	Type	Description
id *	string	Webhook endpoint ID
url	string	New HTTPS target URL
description	string	Optional human-readable label
events	array	Any of job.completed, job.failed, project.budget_warning, or project.budget_exceeded
is_active	boolean	Set false to pause deliveries without deleting the endpoint

Example

curl -X PATCH https://www.agentseo.dev/api/v1/webhooks/endpoints/123e4567-e89b-12d3-a456-426614174000 \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"description":"Primary production hook","is_active":false}'

DELETE/webhooks/endpoints/{id}

Delete a webhook endpoint. This stops future deliveries to that target but does not remove historical delivery records.

Parameters

Name	Type	Description
id *	string	Webhook endpoint ID

Example

curl -X DELETE https://www.agentseo.dev/api/v1/webhooks/endpoints/123e4567-e89b-12d3-a456-426614174000 \
  -H "x-api-key: sk_live_..."

GET/webhooks/deliveries

Inspect recent webhook delivery attempts, response codes, and failure reasons.

Parameters

Name	Type	Description
limit	integer	Number of rows to return (default: 25, max: 100)
status	string	Filter by pending, delivered, or failed
endpoint_id	string	Filter to one webhook endpoint ID
project_id	string	Filter deliveries for one project, including budget alerts
event_type	string	Filter one event type such as project.budget_warning or job.completed

Example

curl https://www.agentseo.dev/api/v1/webhooks/deliveries?limit=25&project_id=client-alpha&event_type=project.budget_exceeded \
  -H "x-api-key: sk_live_..."

POST/webhooks/deliveries/{id}/retry

Retry a failed webhook delivery without re-running the underlying job.

Parameters

Name	Type	Description
id *	string	Webhook delivery ID

Example

curl -X POST https://www.agentseo.dev/api/v1/webhooks/deliveries/123e4567-e89b-12d3-a456-426614174000/retry \
  -H "x-api-key: sk_live_..."

GET/jobs/{id}

Check the status of an async job. Returns progress, attempts, and optional upstream provider status.

Parameters

Name	Type	Description
id *	string	Job ID from 202 response

Example

curl https://www.agentseo.dev/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000 \
  -H "x-api-key: sk_live_..."

GET/jobs/{id}/events

Open an SSE stream for live job updates. Emits events such as job.open, job.status, job.done, and job.failed.

Parameters

Name	Type	Description
id *	string	Job ID from a queued async request

Example

curl -N https://www.agentseo.dev/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000/events \
  -H "x-api-key: sk_live_..." \
  -H "Accept: text/event-stream"