API reference / REST v1

Keywords & competitors

Keyword ideas, metrics, clustering, domain comparisons, and traffic estimates.

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`/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.

Request fields · required fields are labeled
Name	Type	Description
`keywords`Required	array	List of keywords (max 200)

POST /keyword-cluster/build example

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

POST`/keyword-ideas/suggest`

Expand one seed keyword into prioritized long-tail keyword ideas with search volume, CPC, competition, buyer stage, recommended page type, agent_workflow, and markdown_summary. Requests cost 4 credits and use one paid keyword suggestions request with SERP enrichment disabled.

Request fields · required fields are labeled
Name	Type	Description
`keyword`Required	string	Seed keyword or topic
`location`	string	Search market (default: United States)
`location_code`	integer	Optional provider location code. Wins over location when provided.
`language`	string	Language code or name (default: en)
`limit`	integer	Number of ideas to return (5-100, default: 25)
`min_search_volume`	integer	Minimum monthly search volume filter (default: 0)

POST /keyword-ideas/suggest example

curl -X POST https://www.agentseo.dev/api/v1/keyword-ideas/suggest?sync=true \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"seo api", "location":"United States", "language":"en", "limit":25, "min_search_volume":10}'

POST`/keyword-metrics/overview`

Score a supplied keyword list with search volume, CPC, competition, difficulty, buyer stage, recommended page type, opportunity score, agent_workflow, and markdown_summary. Requests cost 5 credits per 25 keywords, minimum 5, with SERP and clickstream enrichment disabled.

Request fields · required fields are labeled
Name	Type	Description
`keywords`Required	array	Keyword list to score. Maximum 100 keywords.
`location`	string	Search market (default: United States)
`location_code`	integer	Optional provider location code. Wins over location when provided.
`language`	string	Language code or name (default: en)
`min_search_volume`	integer	Minimum monthly search volume filter (default: 0)
`sort_by`	enum	priority, search_volume, cpc, or difficulty (default: priority)

POST /keyword-metrics/overview example

curl -X POST https://www.agentseo.dev/api/v1/keyword-metrics/overview?sync=true \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["seo api","best seo api","seo api pricing"], "location":"United States", "language":"en", "min_search_volume":10, "sort_by":"priority"}'

POST`/domain/ranked-keywords`

Find ranked keywords for a domain, subdomain, or URL and prioritize refresh opportunities with rank, page URL, search metrics, SERP features, movement, opportunity type, agent_workflow, and markdown_summary. Requests cost 5 credits per 100 requested rows, minimum 5, with clickstream enrichment disabled.

Request fields · required fields are labeled
Name	Type	Description
`target`Required	string	Domain, subdomain, or page URL to inspect.
`location`	string	Search market (default: United States)
`location_code`	integer	Optional provider location code. Wins over location when provided.
`language`	string	Language code or name (default: en)
`limit`	integer	Rows to request (10-250, default: 50)
`min_search_volume`	integer	Minimum monthly search volume filter (default: 0)
`max_rank`	integer	Maximum ranking position to include (1-100, default: 100)
`sort_by`	enum	opportunity, estimated_traffic, rank, search_volume, or cpc (default: opportunity)
`include_lost`	boolean	Include lost rankings when available (default: false)

POST /domain/ranked-keywords example

curl -X POST https://www.agentseo.dev/api/v1/domain/ranked-keywords?sync=true \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"agentseo.dev", "location":"United States", "language":"en", "limit":25, "min_search_volume":10, "max_rank":50, "sort_by":"opportunity"}'

POST`/domain/relevant-pages`

Find organic traffic-carrying pages for a domain and route them into protect, refresh, expand, recover, or review actions with page metrics, opportunity score, agent_workflow, and markdown_summary. Requests cost 5 credits per 100 requested pages, minimum 5, with clickstream enrichment disabled.

Request fields · required fields are labeled
Name	Type	Description
`target`Required	string	Domain to inspect, without protocol or www when possible.
`location`	string	Search market (default: United States)
`location_code`	integer	Optional provider location code. Wins over location when provided.
`language`	string	Language code or name (default: en)
`limit`	integer	Pages to request (10-250, default: 50)
`min_traffic`	integer	Minimum estimated organic traffic filter (default: 0)
`historical_serp_mode`	enum	live, lost, or all (default: live)
`sort_by`	enum	estimated_traffic, keyword_count, top3, or opportunity (default: estimated_traffic)

POST /domain/relevant-pages example

curl -X POST https://www.agentseo.dev/api/v1/domain/relevant-pages?sync=true \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"agentseo.dev", "location":"United States", "language":"en", "limit":25, "min_traffic":0, "historical_serp_mode":"live", "sort_by":"estimated_traffic"}'

POST`/domain/competitors`

Discover search competitors for a domain and prioritize shared keyword overlap, traffic gaps, threat level, next actions, agent_workflow, and markdown_summary. Requests cost 5 credits per 100 requested competitors, minimum 5, with clickstream enrichment disabled.

Request fields · required fields are labeled
Name	Type	Description
`target`Required	string	Domain or URL to inspect. URLs are normalized to the domain.
`location`	string	Search market (default: United States)
`location_code`	integer	Optional provider location code. Wins over location when provided.
`language`	string	Language code or name (default: en)
`limit`	integer	Competitors to request (5-250, default: 25)
`min_intersections`	integer	Minimum shared keyword count filter (default: 0)
`max_rank_group`	integer	Maximum rank bucket considered for overlap (1-100, default: 20)
`sort_by`	enum	threat, overlap, competitor_traffic, or traffic_gap (default: threat)

POST /domain/competitors example

curl -X POST https://www.agentseo.dev/api/v1/domain/competitors?sync=true \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
              -d '{"target":"agentseo.dev", "location":"United States", "language":"en", "limit":25, "min_intersections":0, "max_rank_group":20, "sort_by":"threat"}'

POST`/domain/intersection`

Compare two domains at keyword level and prioritize shared deficits, current advantages, and target1-exclusive opportunities with rank gaps, traffic gaps, agent_workflow, and markdown_summary. Requests cost 5 credits per 100 requested keywords, minimum 5, with clickstream and extra SERP enrichment disabled.

Request fields · required fields are labeled
Name	Type	Description
`target1`Required	string	First domain or URL. In shared mode this is the domain being compared against target2.
`target2`Required	string	Second domain or URL, usually the competitor selected from /domain/competitors.
`location`	string	Search market (default: United States)
`location_code`	integer	Optional provider location code. Wins over location when provided.
`language`	string	Language code or name (default: en)
`limit`	integer	Keywords to request (5-250, default: 25)
`intersections`	boolean	true returns shared keywords; false returns keywords where target1 ranks and target2 does not (default: true)
`min_search_volume`	integer	Minimum search volume filter (default: 0)
`sort_by`	enum	opportunity, search_volume, traffic_gap, rank_gap, or cpc (default: opportunity)

POST /domain/intersection example

curl -X POST https://www.agentseo.dev/api/v1/domain/intersection?sync=true \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
              -d '{"target1":"hubspot.com", "target2":"salesforce.com", "location":"United States", "language":"en", "limit":25, "intersections":true, "min_search_volume":10, "sort_by":"opportunity"}'

POST`/domain/traffic-estimate`

Compare estimated organic, paid, featured-snippet, and local-pack traffic across multiple domains, subdomains, or URLs before spending deeper analysis credits. Returns footprint type, channel mix, opportunity score, agent_workflow, and markdown_summary. Requests cost 5 credits per 25 supplied targets, minimum 5.

Request fields · required fields are labeled
Name	Type	Description
`targets`Required	string[]	Domains, subdomains, or absolute page URLs to estimate (1-100).
`location`	string	Search market (default: United States)
`location_code`	integer	Optional provider location code. Wins over location when provided.
`language`	string	Language code or name (default: en)
`include_paid`	boolean	Include paid-search traffic estimates (default: true)
`include_featured_snippet`	boolean	Include featured-snippet traffic estimates (default: true)
`include_local_pack`	boolean	Include local-pack traffic estimates (default: false)
`sort_by`	enum	organic_traffic, total_traffic, paid_traffic, opportunity, or target (default: organic_traffic)

POST /domain/traffic-estimate example

curl -X POST https://www.agentseo.dev/api/v1/domain/traffic-estimate?sync=true \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"targets":["hubspot.com","salesforce.com","zendesk.com"], "location":"United States", "language":"en", "include_paid":true, "include_featured_snippet":true, "include_local_pack":false, "sort_by":"organic_traffic"}'

POST`/pages/intersection`

Compare ranking pages to find shared page keywords or competitor-page keywords excluded from your pages. Returns search volume, page ranks, rank spread, traffic gap, intent, SERP features, priority, agent_workflow, and markdown_summary. Requests cost 5 credits per 100 requested keywords, minimum 5. Clickstream enrichment doubles the credit cost.

Request fields · required fields are labeled
Name	Type	Description
`pages`Required	string[]	Absolute page URLs or wildcard URL patterns to compare. Maximum 5.
`exclude_pages`	string[]	Absolute page URLs or wildcard URL patterns to exclude, usually your own page group. Maximum 5.
`location`	string	Search market (default: United States)
`item_types`	string[]	organic, paid, featured_snippet, or local_pack (default: organic and featured_snippet)
`limit`	integer	Keywords to request, 5-100 (default: 25)
`intersection_mode`	enum	union or intersect (default: union). Use intersect when all supplied pages must rank for the keyword.
`include_serp_info`	boolean	Include SERP feature metadata for each keyword (default: false)
`include_clickstream_data`	boolean	Include clickstream-normalized metrics. Doubles credit cost (default: false).
`min_search_volume`	integer	Minimum search volume filter (default: 0)
`max_rank`	integer	Maximum rank for the first supplied page, 1-100 (default: 30)
`sort_by`	enum	opportunity, search_volume, traffic_gap, rank, or cpc (default: opportunity)

POST /pages/intersection example

curl -X POST https://www.agentseo.dev/api/v1/pages/intersection?sync=true \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pages":["https://www.hubspot.com/products/crm/*","https://www.salesforce.com/crm/*"], "exclude_pages":["https://www.agentseo.dev/*"], "location":"United States", "limit":25, "intersection_mode":"union", "include_clickstream_data":false, "sort_by":"opportunity"}'

← All endpoints

POST/keyword-cluster/build

POST/keyword-ideas/suggest

POST/keyword-metrics/overview

POST/domain/ranked-keywords

POST/domain/relevant-pages

POST/domain/competitors

POST/domain/intersection

POST/domain/traffic-estimate

POST/pages/intersection