# 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](https://www.agentseo.dev/docs/async-jobs) · [Errors and limits](https://www.agentseo.dev/docs/errors) · [OpenAPI contract](https://www.agentseo.dev/openapi.yaml)

## 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](https://www.agentseo.dev/docs/api-reference)

---
Canonical HTML: https://www.agentseo.dev/docs/api-reference/keywords
Markdown: https://www.agentseo.dev/docs/api-reference/keywords/index.md