---
title: "SEO opportunity"
method: GET
path: "/sites/{site}/seo-opportunities/{opportunity_id}"
tags: ["Analytics"]
---

# SEO opportunity

`GET /sites/{site}/seo-opportunities/{opportunity_id}`

## Request

- Base URL: `https://api.onelence.com/v1`
- URL: `https://api.onelence.com/v1/sites/{site}/seo-opportunities/{opportunity_id}`
- Auth: one of:
  - OAuth 2 (authorization code, authorization URL `https://api.onelence.com/oauth/authorize`, token URL `https://api.onelence.com/oauth/token`, scopes: `analytics:read`)
  - HTTP bearer

One SEO opportunity from the opportunities list, with the brief the SEO page shows: what to do, the page and query it targets, what to change and check, why now, the facts behind it with where each comes from, and any blockers. Pass the same window as the list, if any.

## Path parameters

- `site` string, required
- `opportunity_id` string, required

## Query parameters

- `start` string
- `end` string

## Response `200`

Success.

- object
  - `object` 'seo_opportunity', required
  - `id` string, required
  - `kind` string, required
  - `page` string, nullable, required
  - `query` string, nullable, required
  - `topic` string, nullable, required
  - `lane` 'grow_proven_pages' | 'recover_visibility' | 'fix_search_leakage' | 'create_new_coverage' | 'needs_evidence', required
  - `search_potential` 'high' | 'medium' | 'low' | 'missing', required
  - `page_value` 'high' | 'medium' | 'low' | 'missing', required
  - `confidence` 'high' | 'medium' | 'low' | 'missing', required
  - `urgency` 'high' | 'medium' | 'low' | 'missing', required
  - `effort` string, nullable, required
  - `page_visitors` number, nullable, required
  - `page_conversions` number, nullable, required
  - `title` string, required
  - `why` string, nullable, required
  - `next_step` string, nullable, required
  - `focus_queries` string[], required
  - `conflicts` string[], required
  - `disposition` 'ready_to_plan' | 'check_first' | 'explore_only' | 'in_work' | 'excluded', required
  - `primary_reason` string, required
  - `candidate_fingerprint` string, required
  - `action_state` 'opportunity' | 'evaluation' | 'work' | 'none' | 'unavailable', required
  - `brief` object, nullable, required
    - `state` 'ready' | 'blocked' | 'research_missing', required
    - `heading` string, required
    - `target` string, nullable, required
    - `focus_query` string, nullable, required
    - `do_this` string, required
    - `now` string, required
    - `change` string, required
    - `check` string, required
    - `why_now` string, required
    - `facts` object[], required
      - `label` string, required
      - `value` string, required
      - `basis` string, required
      - `as_of` string, nullable, required
    - `blockers` string[], required

## Other responses

- `400`: Invalid input; `error.param` names the field.
- `401`: Missing, expired or revoked token. WWW-Authenticate points to the resource metadata.
- `402`: subscription_required or upgrade_required; the error carries billing_url.
- `403`: insufficient_scope or admin_required.
- `404`: Unknown endpoint, site, source or record.
- `429`: Rate limited. Retry after Retry-After seconds.
- `500`: OneLence could not complete the request.

---

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