Opportunities

GEThttps://api.boringmarketing.com/brands/{brand_id}/opportunities

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

Path parameters

brand_idstringrequired

The brand UUID.

Query parameters

run_idstring

Pin to a specific run. When omitted, returns opportunities from the latest completed run.

Response

{
  "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}` 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

curl -H "X-API-Key: $BM_API_KEY" \
  "https://api.boringmarketing.com/brands/$BRAND_ID/opportunities"