---
title: "Find SEO opportunities"
method: POST
path: "/opportunities/find"
---

# Find SEO opportunities

`POST /opportunities/find`

## Request

- Base URL: `https://www.agentseo.dev/api/v1`
- URL: `https://www.agentseo.dev/api/v1/opportunities/find`
- Auth: API key in header `x-api-key`

Find prioritized keyword and page opportunities for a domain or URL. Costs 3 credits base, plus 2 credits for SERP competitor enrichment and 2 credits for domain competitor discovery.

## Query parameters

- `sync` boolean

## Headers

- `x-project-id` string
- `x-workflow-id` string

## Request body

- OpportunitiesFindParams
  - `target` string, required: Domain or URL to analyze.
  - `location` string
  - `location_code` integer: Optional search location code for deterministic geo-targeting.
  - `language` string
  - `keyword_limit` integer
  - `opportunity_limit` integer
  - `include_serp_competitors` boolean: Adds SERP competitor enrichment and increases request cost by 2 credits.
  - `include_competitor_discovery` boolean: Adds domain competitor discovery and increases request cost by 2 credits.

## Response `200`

Completed opportunity finder workflow with priorities and agent_workflow

- OpportunitiesFindResponse
  - `target` string
  - `opportunities` SeoOpportunity[]
    - `keyword` string
    - `type` 'quick_win' | 'content_refresh' | 'ai_overview_opportunity' | 'featured_snippet_opportunity' | 'commercial_intent_opportunity' | 'lost_keyword_recovery' | 'competitor_gap'
    - `priority` 'high' | 'medium' | 'low'
    - `score` integer
    - `current_rank` integer, nullable
    - `target_url` string, nullable
    - `reason` string
    - `evidence` AgentWorkflowEvidence[]
      - `finding` string
      - `detail` string
      - `severity` 'critical' | 'high' | 'medium' | 'low'
    - `recommended_actions` string[]
    - `next_calls` AgentWorkflowNextCall[]
      - `endpoint` string
      - `reason` string
  - `competitors` object[]
  - `agent_workflow` AgentWorkflow
    - `summary` string
    - `decision` 'ready' | 'act_now' | 'monitor' | 'blocker'
    - `confidence` number
    - `recommended_actions` AgentWorkflowAction[]
      - `priority` 'critical' | 'high' | 'medium' | 'low'
      - `action` string
      - `why` string
    - `evidence` AgentWorkflowEvidence[]
      - `finding` string
      - `detail` string
      - `severity` 'critical' | 'high' | 'medium' | 'low'
    - `limitations` string[]
    - `next_calls` AgentWorkflowNextCall[]
      - `endpoint` string
      - `reason` string
  - `markdown_summary` string

## Other responses

- `202`: Job queued or still processing

---

[API](https://skmtc.dev/agentseo/apis/agentseo-api.md) · [All operations](https://skmtc.dev/agentseo/apis/agentseo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentseo/apis/agentseo-api/revisions/53a62da6f92c?raw)