---
title: 'The data-backed path: a research run, ranked clusters, a content plan'
description: 'What a research run does and costs, how opportunity clusters rank and filter, the levers that reshape them, and how a run becomes a content plan with briefs.'
slug: data-backed-path
group: workflows
order: 10
keywords:
  [
    research run,
    start_research_run,
    opportunity clusters,
    list_opportunities,
    content plan,
    competitor importance,
    excluded terms,
  ]
related: [your-first-project, from-your-own-ideas, free-and-paid, drafting-and-verification]
updated: '2026-10-26'
---

The data-backed path starts from search data instead of from an idea. A research run maps the niche, the opportunities rank what to write, and the content plan turns the best of them into briefs. It needs a paid plan.

## What a research run does

`start_research_run` discovers keywords for the niche, reads who ranks for them, evaluates those competitors and groups the keywords into opportunity clusters. Each run spends one research credit, and your agent asks you before it starts one. On the free plan the call returns a structured wall instead of a run.

The call returns a `runId`. Over MCP it can start at most once a minute, a guard against an agent looping on your credits.

## Waiting for it

A run takes about an hour. Your agent tells you that, then polls `get_research_status` once every 30 to 60 seconds at most. Each poll returns a small fixed shape: `status`, the current `phase`, `percentComplete` and `elapsedSeconds`.

A failed run carries a `failure` object with a `failureClass` and a `retryable` flag. `true` means a passing upstream problem and a retry is safe. `false` means a retry will fail the same way. A run still in the `initializing` phase after a long time is stalled, not queued, and your agent reports it.

In the web app, the project overview shows the same run as a four-step progress bar (Discover, SERP, Profile, Cluster) and says to expect about an hour.

## Reading the opportunities

`list_opportunities` returns clusters ranked by opportunity score, from 0 to 100 against the highest-scoring visible cluster. Four goal filters narrow the list without changing any score:

| Goal                 | A cluster qualifies when                                         |
| -------------------- | ---------------------------------------------------------------- |
| `fast_wins`          | a keyword has an average or high volume band and difficulty ≤ 40 |
| `high_intent`        | a keyword is commercial or transactional                         |
| `authority_building` | it has informational keywords and no commercial or transactional |
| `competitor_gap`     | it is a gap and a competitor you marked important ranks top 10   |

Coverage decides what you see by default. Clusters that are a `gap` or `partial` show; clusters your site already `covered` stay hidden unless the agent asks for them, as refresh candidates. A cluster your product cannot serve carries a `fitFlag` with a plain reason and is scored down, not hidden.

`get_opportunity_detail` opens one cluster: its top 20 keywords, the top 10 ranked pages, a podium of the top 5 competitors, linked suggestions and the un-normalized `rawOpportunityScore`.

## Shaping the list

Three levers change the ranking, and each one moves the 0 to 100 scale for every other cluster:

- `set_opportunity_status` with `dismissed` hides one cluster from the list and from the plan harvest; `default` brings it back. A dismissal lasts until the next run rewrites the clusters.
- `set_excluded_terms` names what you do not sell, up to 30 terms. Keywords mentioning them are scored down and left out of the harvest. The call replaces the whole list, and the list survives new runs.
- `set_competitor_importance` is the one competitor lever. `important` boosts clusters where that competitor ranks top 10 by 1.25x; `ignored` drops it from the competitor surfaces and the rankings.

## From opportunities to a content plan

`create_content_plan_from_opportunities` harvests the top 30 clusters into article suggestions, one per cluster. It skips dismissed clusters, fit-flagged clusters, excluded keywords and clusters your site already covers at 80% or more. Calling it again reuses the plan and skips clusters that already have a suggestion. Because it can add up to 30 suggestions at once, your agent confirms with you first.

To pick clusters one at a time instead, use the web app's Forge brief button on a cluster, which links the suggestion to that cluster. Over MCP, the nearest call is `add_article_suggestion` with the cluster's title; it creates a suggestion from the title alone, without the cluster link.

Either way, briefs forge on their own. Each suggestion lands in `generating_brief`, and `download_brief_markdown` returns its brief once it reports `brief_ready`. No `generate_article_brief` call is needed.

## What you see in the web app

The Opportunities screen shows every cluster as cards or a table, with the goal filters, a coverage dropdown, sub-niche tabs and a gold star on the strongest picks. Each cluster not yet in the plan has Forge brief and a Dismiss button with an undo.

The Content Plan screen is a board with one column per status, up to `published`. Next comes [drafting and verification](/docs/drafting-and-verification).