---
title: Signals & Opportunities
description: "How the API detects opportunity signals across 6 search surfaces and converts them into scored, actionable opportunities with priority rankings."
---
> **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.
The API monitors multiple search surfaces for signals — patterns that indicate a content opportunity for your brand. Signals are detected, scored, and packaged into **opportunities** with clear next actions.
## The 6 search surfaces
The product watches six distinct search surfaces for gaps and movement:
| Surface | What it is |
|---------|-----------|
| **Google Organic** | Traditional blue-link Google search results |
| **Google AI Overviews** | The AI-generated summary at the top of Google results |
| **Google AI Mode** | Google's conversational AI search experience |
| **ChatGPT / Copilot** | OpenAI and Microsoft conversational AI |
| **Perplexity** | Perplexity.ai conversational search |
| **Claude / Gemini** | Anthropic and Google conversational AI |
## Signal categories
Across those six surfaces, the detection layer produces signals in the following categories:
| Category | What it monitors | Example signal |
|----------|-----------------|----------------|
| **Discovery** | Missing topics, cluster gaps, geo gaps | Your brand has no content for a high-intent keyword family |
| **AI / Citations** | LLM citation presence across ChatGPT, Perplexity, Claude, Gemini | You rank on Google but no LLM cites you |
| **Competitor** | Competitor keyword gaps, competitive moves | A competitor ranks for keywords you don't cover |
| **SERP** | Organic result weakness, feature snippets | A weak page holds position 3 — takeover opportunity |
| **Rank** | Striking distance keywords (positions 11-20) | You're on page 2 for a high-value keyword |
| **Site** | Internal links, schema, CTAs, technical audit findings | Orphan pages with no internal links |
| **Timeseries** | Ranking decay, defensive priorities | A page dropped 15 positions in 30 days |
## From signal to opportunity
```mermaid
graph LR
A[Search Surface] -->|Detection| B[Signal]
B -->|Scoring| C[Opportunity]
C -->|Ranking| D[Action Queue]
D -->|Execution| E[Brief + Draft]
E -->|Measurement| F[Outcome]
F -->|Learning| A
```
Each signal passes through deterministic scoring before becoming an opportunity. No signal reaches the queue without evidence and an actionable next step.
## Scoring
Every opportunity carries two scores that combine into a priority:
**Immediacy** — how easy and fast to win:
- Keyword difficulty (inverted) — 60%
- Gap boost (brand absent) — 20%
- Type boost (high-intent, comparison) — 12%
- Greenfield bonus (no competitor dominates) — 8%
**Ceiling** — how big the prize:
- Search volume — 40%
- Business value — 30%
- Intent alignment — 20%
- AI Overview bonus — 10%
**Priority = 0.5 * immediacy + 0.5 * ceiling**
The highest-priority opportunities appear first in your action queue.
## Opportunity object
Every opportunity includes these fields:
```json
{
"id": "opp-uuid",
"family": "Marketing Automation",
"play": "AI Marketing Tools Comparison Guide",
"summary": "No ranking content for high-intent cluster — 12K monthly volume, KD 34",
"recommended_format": "comparison",
"keywords": [
{ "keyword": "ai marketing tools", "google_vol": 18000 },
{ "keyword": "best ai marketing software", "google_vol": 14500 }
],
"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"
}
```
Key guarantees:
- Every opportunity has evidence (`contributing_signals[].evidence_id` resolves against `GET /brands/{id}/evidence/{evidence_id}`)
- Every opportunity has a `recommended_format` from `{hub_and_spokes, single_article, programmatic, comparison, landing_page}`
- Every opportunity traces back to specific keywords and topic families
- `why_now` / `next_action` / `expected_impact` are top-level fields ready for agent consumption (may be `null` on legacy rows)
## Action templates
**Action templates are a planned execution layer**, not a wired API surface today. The taxonomy lives in `docs/action-template-contracts-v1.yaml` as the canonical reference, but the pipeline does not currently emit a `template` field on opportunities, and there is no API endpoint that maps an opportunity to a template. Use `recommended_format` and `next_action` from the opportunity object as the actionable signals for now.
| Template (planned) | When it fires |
|----------|--------------|
| `create_net_new_page` | Brand has no content for this opportunity |
| `refresh_existing_page` | Existing page is decaying or under-performing |
| `build_hub_and_spokes` | Topic family needs a hub page with supporting articles |
| `competitive_response_pack` | Competitor pressure requires multiple response assets |
| `optimize_on_page_and_schema` | Page exists but needs on-page/schema improvements |
| `internal_link_rollout` | Link architecture gaps reduce page authority |
## Portfolio balance
The scoring system targets a balanced portfolio:
- **60%** near-term wins — low difficulty, clear gaps, quick to publish
- **30%** category authority plays — hub-and-spokes, pillar content
- **10%** strategic bets — emerging topics, AI-surface plays
This prevents the common trap of only chasing easy keywords while ignoring long-term positioning.
Follow an opportunity from queue to published content and tracked outcomes.
Full endpoint reference for fetching scored opportunities.