---
title: Opportunities
api: GET /brands/{brand_id}/opportunities
description: "Get ranked content opportunities sorted by priority score."
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://docs.boringmarketing.com/llms.txt). Append `.md` to any page URL for its markdown version.

Returns scored opportunities from the latest pipeline run. Each opportunity includes keywords, scoring breakdown, and a recommended content format.

## Path parameters

<ParamField path="brand_id" type="string" required>
  The brand UUID.
</ParamField>

## Query parameters

<ParamField query="run_id" type="string">
  Pin to a specific run. When omitted, returns opportunities from the latest completed run.
</ParamField>

## Response

```json
{
  "brand_id": "brand-uuid",
  "total": 42,
  "opportunities": [
    {
      "id": "opp-uuid",
      "brand_id": "brand-uuid",
      "run_id": "run-uuid",
      "family": "Marketing Automation",
      "play": "AI Marketing Tools Comparison Guide",
      "summary": "No ranking content for high-intent 'ai marketing tools' cluster — 12K monthly volume, KD 34",
      "recommended_format": "comparison",
      "format_rationale": "Buyers explicitly compare 4-6 tools before purchase",
      "keywords": [
        { "keyword": "ai marketing tools", "google_vol": 18000 },
        { "keyword": "best ai marketing software", "google_vol": 14500 },
        { "keyword": "ai content marketing", "google_vol": 12500 }
      ],
      "total_volume": 45000,
      "rank": 1,
      "immediacy": 0.85,
      "ceiling": 0.78,
      "priority": 0.92,
      "leverage_score": 1.10,
      "contributing_signals": [
        { "evidence_id": "ev-1", "signal": "missing_topic_gap", "type": "gap_signal", "role": "primary" },
        { "evidence_id": "ev-9", "signal": "aio_present", "type": "serp_pattern", "role": "supporting" }
      ],
      "why_now": "AIO is forming for this cluster — 90 days to set the citation pattern",
      "next_action": "Draft a 2,500-word comparison post with FAQPage schema",
      "expected_impact": "Top-3 rank within 60 days; AIO citation within 90",
      "created_at": "2026-04-08T12:00:00Z",
      "updated_at": "2026-04-08T12:00:00Z"
    }
  ]
}
```

| Field | Description |
|-------|------------|
| `priority` | Combined score: `0.5 * immediacy + 0.5 * ceiling` (0–1 scale) |
| `immediacy` | How quick/easy to win — factors in KD, gaps, greenfield (0–1 scale) |
| `ceiling` | How big the prize — volume, business value, intent, AIO bonus (0–1 scale) |
| `leverage_score` | Post-leverage re-rank score after `POST /brands/{id}/score` runs. `null` until scoring runs. |
| `total_volume` | Sum of monthly search volume across this opportunity's keywords |
| `rank` | Position in the portfolio after sorting by `priority` (1 = top) |
| `recommended_format` | One of `hub_and_spokes`, `single_article`, `programmatic`, `comparison`, `landing_page` |
| `format_rationale` | Why this format was chosen |
| `keywords` | Array of keyword dicts. Always contains `keyword`; other fields (`google_vol`, etc.) are best-effort and may be missing. |
| `contributing_signals` | Array of `{evidence_id, signal, type, role}`. Resolve `evidence_id` against [`GET /brands/{id}/evidence/{evidence_id}`](https://docs.boringmarketing.com/api-reference/results/evidence) for the underlying data. |
| `why_now` / `next_action` / `expected_impact` | Promoted from the LLM synthesis context to top-level fields for agent consumption. May be `null` on legacy rows. |

## Example

<CodeGroup>
```bash cURL
curl -H "X-API-Key: $BM_API_KEY" \
  "https://api.boringmarketing.com/brands/$BRAND_ID/opportunities"
```

```python Python
opps = httpx.get(
    f"https://api.boringmarketing.com/brands/{brand_id}/opportunities",
    headers={"X-API-Key": api_key},
).json()

for opp in opps["opportunities"][:5]:
    print(f"[{opp['priority']:.2f}] {opp['play']}")
    print(f"  Keywords: {', '.join(opp['keywords'][:3])}")
    print(f"  Format: {opp['recommended_format']}")
```
</CodeGroup>