---
title: 'Research History: every research run on a project, past and live'
description: 'What a row on Research History shows, how a live run is tracked, what happens to a failed run and its credit, how to start another, and the MCP calls that do the same.'
slug: research-history
group: app
order: 33
keywords:
  [research history, research run, start_research_run, get_research_status, research credit, failed run, pitch report]
related: [data-backed-path, project-overview, client-reports, free-and-paid]
updated: '2026-10-26'
---

Research History is the last item under a project in the sidebar. It lists every research run on the project, newest first, and shows the one in progress. A run is what turns a niche into ranked opportunities; [the data-backed path](/docs/data-backed-path) explains what it does.

## What the screen shows

A line under the heading says how old the project's data is.

While a run is going, a **Research in Progress** card sits at the top with four figures: **Duration**, **Est. Finish**, **Keywords** and **Competitors**. Below them, **Currently analyzing** names the keyword or competitor being worked on, and a bar shows percent complete and minutes remaining. That bar tracks time, not work done: it assumes about an hour from the start and never projects less than five minutes ahead. When the run finishes, the table refreshes on its own.

Each finished run is a row:

| Column    | What it holds                                        |
| --------- | ---------------------------------------------------- |
| (icon)    | A check for completed, an alert for failed           |
| Run ID    | The first 12 characters of the run's id              |
| Started   | Date and time the run began                          |
| Duration  | Start to end, or a dash when no end time is recorded |
| Keywords  | Keywords discovered                                  |
| Companies | Companies discovered                                 |
| Status    | `completed` or `error`                               |

A completed row also has a **Pitch report** button.

## Phases and errors

A run moves through four phases: Discover, SERP, Profile and Cluster. The rows do not show them. The live phase appears on the [project Overview](/docs/project-overview) while the run is going, and from `get_research_status`, which reports `initializing` before the first phase starts.

A failed row shows only the `error` status. The Overview explains the failure in plain words on its error card. Over MCP, `get_research_status` returns a `failure` object with a `failureClass`, the phase the run died in and a `retryable` flag, for the latest run only.

A run still marked running after two hours is treated as stuck and closed as failed; the check runs every 15 minutes.

## Credits

Starting a run spends one research credit, and the confirmation says so. A failed run gives its credit back, stuck runs included, so a failure leaves your balance where it was. Credits per plan are on [Free and paid](/docs/free-and-paid).

## What you can do here

- **New Research** opens **Start New Research**, which states the credit cost, with **Cancel** and **Start Research**. While a run is in progress the button is disabled, with the tooltip "A research is already in progress". With no runs yet, the empty state offers **Start First Research**.
- There is no retry button on a failed row. Start a new run here, or use **Retry Analysis** on the Overview's error card; either one spends a credit, and the failed run's credit has already been returned.
- **Pitch report** downloads a VarynForge-branded PDF of that run. When your site profile was last synced before the run, a dialog first offers **Re-sync profile first** or generating with the profile as it is. [Client reports](/docs/client-reports) covers the report itself.

## The same runs over MCP

- `start_research_run` starts a run and returns its `runId`. Over MCP it can start at most once a minute.
- `get_research_status` reads the latest run only. No MCP tool lists past runs.
- `get_pitch_report_payload` takes a completed run's `runId` and returns the pitch report as data to render in your own template. `resync_asset_profile` is the re-sync choice.