# Opportunities & signals

Find opportunities, prepare briefs, and inspect social demand signals.

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`/opportunities/find`

Find ranked-keyword opportunities for a domain or URL and return agent-ready priorities, evidence, recommended actions, next API calls, and a markdown summary. Base requests cost 3 credits; SERP competitor enrichment adds 2 credits; domain competitor discovery adds 2 credits.

Request fields · required fields are labeled

| Name | Type | Description |
| --- | --- | --- |
| `target`Required | string | Domain, subdomain, or URL to analyze (e.g. example.com or https://example.com/blog) |
| `location` | string | Target location (default: United States) |
| `location_code` | integer | Optional search location code for deterministic geo-targeting |
| `language` | string | ISO code (default: en) |
| `keyword_limit` | integer | How many ranked keywords to inspect (10-250, default: 100) |
| `limit` | integer | How many opportunities to return (1-25, default: 10) |
| `seed_keywords` | array | Optional keywords for SERP competitor enrichment; if omitted, AgentSEO can auto-select ranked keywords |
| `include_serp_competitors` | boolean | Add SERP competitor domains for the selected keyword set (+2 credits) |
| `include_competitor_discovery` | boolean | Add domain-level competitor gaps and overlap metrics (+2 credits) |

POST /opportunities/find example

```
curl -X POST https://www.agentseo.dev/api/v1/opportunities/find?sync=true \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"example.com", "location":"United States", "keyword_limit":10, "limit":3, "include_serp_competitors":true, "include_competitor_discovery":true}'
```

## POST`/opportunities/brief`

Turn one selected keyword/page opportunity into an implementation-ready brief with SERP intent, sections to add, questions to answer, schema recommendations, validation checklist, agent\_workflow, and markdown\_summary. Base requests cost 10 credits; competitor outline scraping adds 2 credits.

Request fields · required fields are labeled

| Name | Type | Description |
| --- | --- | --- |
| `keyword`Required | string | Keyword to analyze and brief |
| `target` | string | Target domain, brand, or site being optimized |
| `page_url` | string | Existing page URL to inspect for current headings |
| `location` | string | Target location (default: United States) |
| `location_code` | integer | Optional search location code for deterministic geo-targeting |
| `language` | string | ISO code (default: en) |
| `opportunity_type` | string | Optional hint such as quick\_win, content\_refresh, ai\_overview\_opportunity, featured\_snippet\_opportunity, commercial\_intent\_opportunity, lost\_keyword\_recovery, or competitor\_gap |
| `current_rank` | integer | Known current rank for priority shaping |
| `include_competitor_outlines` | boolean | Scrape headings from top SERP competitors for outline context (+2 credits, default: true) |

POST /opportunities/brief example

```
curl -X POST https://www.agentseo.dev/api/v1/opportunities/brief?sync=true \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"seo api", "target":"example.com", "page_url":"https://example.com/seo-api", "location":"United States", "opportunity_type":"commercial_intent_opportunity", "current_rank":8, "include_competitor_outlines":false}'
```

## 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.

Request fields · required fields are labeled

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

POST /social/listen example

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

[← All endpoints](https://www.agentseo.dev/docs/api-reference)

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