---
title: "List Opportunities"
method: GET
path: "/v1/opportunities"
tags: ["Opportunities"]
---

# List Opportunities

`GET /v1/opportunities`

## Request

- Base URL: `https://api.lightsage.com`
- URL: `https://api.lightsage.com/v1/opportunities`
- Auth: API key in header `X-Lightsage-Api-Key`

Returns ranked opportunities from stored prompt visibility results.

The default window is the previous 30 days. Each opportunity includes an
`execution_prompt` with the context an AI agent needs to address it. Results
are recomputed for the requested window, but this endpoint does not run new
prompts.

## Query parameters

- `since` string
- `start_date` string
- `end_date` string
- `category` 'quick_wins' | 'growth' | 'refresh' | 'citations'
- `opportunity_type` 'almost_winning' | 'negative_sentiment' | 'lost_wins' | 'competitor_gaps' | 'untapped_topics' | 'platform_blind_spots' | 'content_gaps' | 'declining_visibility' | 'volatile_visibility' | 'citation_gaps' | 'high_citation_sources' | 'listicle_targets'
- `limit` integer

## Response `200`

Successful Response

- ListOpportunitiesResponse
  - `start_date` string, required: Window start actually used, after resolving `start_date`, `since`, or the default.
  - `end_date` string, required
  - `data` PublicPromptOpportunity[]
    - `id` string, required: Stable across requests and windows for the same finding. There is no retrieve endpoint.
    - `type` string, required: Determines which undeclared extra fields the object carries, such as `winner_brand_name` on `almost_winning`.
    - `category` string, required
    - `priority` string, required
    - `title` string, required
    - `description` string, required
    - `action` string, required
    - `execution_prompt` string, required
    - `impact_score` number, required: Out of 100. Recomputed per window, so the same `id` can score differently across windows.
    - `created_at` string, required: Time of the request, since opportunities are computed per call.
  - `count` integer, required: Capped by `limit`; not the total available.
  - `summary` object: Breakdowns of the returned items only; each sums to `count`.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/usesapient/apis/sapient-public-api.md) - [All operations](https://skmtc.dev/usesapient/apis/sapient-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/usesapient/apis/sapient-public-api/revisions/14890dfe867e?raw)