> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surfacd.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Buying Stages

> See where AI recommends you in the buying journey, from first learning about a problem to choosing who to buy from.

A buyer asks AI different questions as they move towards a purchase. Early on they're learning about a problem, then they compare ways to solve it, and finally they choose a supplier. Buying stages tag every prompt with the point in that journey it belongs to, so you can see whether AI recommends you early, late or not at all.

> [!NOTE]
>
> Buying stages and [personas](https://docs.surfacd.com/docs/personas.md) are available to all teams. They're in beta, marked **New** in the app, and details may change.

Buying stages are part of the new version of Surfacd. If you're using the classic version, switch with **Try new version** in the header.

## The Three Stages

Every prompt is at exactly one stage.

| Stage | In the app | What the person asking is doing | Example prompts |
| - | - | - | - |
| **Awareness** | Learning about a problem or topic | Learning about a business problem or topic, or asking for facts about a company, such as who owns it or what it does | "What is a CDP?", "Why is my email open rate low?", "Who owns Acme?" |
| **Consideration** | Comparing ways to solve it | Exploring the market without judging one supplier yet: "best X for Y", category lists, approaches and alternatives | "Best CRM for small businesses", "Alternatives to Salesforce", "How do teams automate SOC 2 evidence?" |
| **Decision** | Choosing who to buy from | Judging a named company or product, or a shortlist of two or three: comparisons, pricing, reviews, fit, trust, security and due diligence, trials and migration | "HubSpot vs Marketo", "How much does Slack cost?", "Is Asana secure enough for enterprise?" |

A list of the best products in a category stays at Consideration, even when it names products. Once the question is about one named product, or a head-to-head between two or three, it's at Decision.

## How Prompts Get a Stage

### Automatic classification

Surfacd classifies every new prompt shortly after it's added, however you add it: by hand, from a file, from suggestions, by copying to another country, or through the API or an AI assistant. It reads the prompt's words alongside your brand, your marked competitors and your target audience, and picks the stage the person asking is most likely at.

Classification usually takes a few minutes. Until it's done, a new prompt shows **Consideration**.

### Correcting a stage

If a prompt's stage looks wrong, change it on the **Prompts** page:

**1. Find the prompt**

Open **Prompts**. The **Buying stage** column shows each prompt's stage. If it's hidden, turn it on with the table settings button beside the search box.

**2. Pick the right stage**

Click the prompt's stage and choose another from the menu. Each option says what the stage means.

The change saves straight away. Surfacd won't reclassify a prompt after you've picked its stage. Team members and admins can change stages, and viewers see them read-only.

> [!NOTE]
>
> A prompt's answers are reported under its current stage, so changing a stage moves the prompt's history to the new stage too. Changing a stage doesn't use credits or count towards your prompt limit.

A prompt and the prompts asking it as [personas](https://docs.surfacd.com/docs/personas.md) always share one stage: they ask the same words. Changing the stage on any of them changes it for all of them.

## Filtering and Breaking Down by Stage

* **Filter:** the filter bar has a **Buying stage** filter. It sits in the bar while there's room, or under the **+** menu. Pick one or more stages to see results for just those prompts. Like other filters, it carries across pages, can be kept in a saved filter and applies to exports.
* **Prompts:** group the table **By buying stage** to see your prompts from awareness to decision, with each stage's numbers. Exporting the prompts list adds a **Buying stage** column with each prompt's stage, so you can sort or pivot the file by stage.
* **Visibility › Overview:** choose **Buying stages** in the **Compare** menu to rank you at each stage, or pick Buying stages as the rows or columns of the **Breakdown**.
* **Details:** select a stage anywhere it's listed to open its details. The details of a brand, platform, topic, country or cited site also break down by buying stage, and a prompt's details show its stage.

## The Buying Journey

The **Buying journey** section on **Visibility › Overview** shows how visible you are at each stage, for your Baseline and for each persona.

![The Buying journey section with a funnel of visibility at Awareness, Consideration and Decision, beside a table of the Baseline and three personas at each stage](https://mintcdn.com/surfacd/mbMAKpBDuamf4guS/images/buying-stages/buying-journey.png?fit=max\&auto=format\&n=mbMAKpBDuamf4guS\&q=85\&s=fc85ecf37968da15e5dc4939957fedc9)

Visibility › Overview › Buying journey: your funnel on the left, each persona by stage on the right

**Visibility by buying stage** is a funnel with a tier for each stage, from Awareness to Decision. Each tier shows your visibility across your active prompts at that stage. Hover over a tier to see what the stage means, how many prompts it has and its change on the previous period.

* A stage with no prompts shows **No prompts**, and one with prompts but no answers in the dates shows **No answers yet**. Both stay in the funnel, greyed out.
* Each tier and cell is shaded by your visibility, in steps of 20 points: the deeper the shade, the more visible you are. The key under the funnel runs from 0% to 100%.

**Personas** lists the Baseline first, then each persona, best first. Each row shows your visibility at awareness, consideration and decision, and overall. A stage without answers shows "—". Hover over a row for its prompt count and its change on the previous period.

Select a persona to narrow the funnel to that persona's prompts. The funnel's title changes to that persona's funnel, and **All prompts** takes you back. **View all** opens the Personas view on Visibility.

Until a persona has asked prompts, the Personas panel explains what personas add and links to **Manage Personas**. The funnel works without personas.

### Personas by stage

On **Visibility › Personas**, the **Persona breakdown** compares each persona at each buying stage by default. It's the quickest way to see where one buyer drops off: a persona that AI recommends you to at Decision but not at Awareness may not find you until it already knows your name.

![The Persona breakdown table with the Baseline and three personas as rows and Awareness, Consideration and Decision as columns](https://mintcdn.com/surfacd/mbMAKpBDuamf4guS/images/buying-stages/persona-stage-breakdown.png?fit=max\&auto=format\&n=mbMAKpBDuamf4guS\&q=85\&s=d55d0deb3223a3e47f0b7b0202f74090)

Visibility › Personas › Persona breakdown, comparing buying stages

## Tips

* **Cover every stage.** If a stage has only a handful of prompts, its numbers move a lot from one run to the next. Aim for a similar number of prompts at each stage. Group the Prompts page **By buying stage** to check.
* **Fix stages that matter.** Correct the prompts whose stage changes how you read a report, such as a product comparison classified as Consideration. You don't need to review every prompt.
* **Read Decision with care.** Decision prompts often name your brand, which makes you easier to find. Awareness and Consideration show whether AI recommends you before a buyer knows your name.
* **Combine with personas.** Ask your most important prompts as [personas](https://docs.surfacd.com/docs/personas.md) to see which buyers find you at which stage.

## API & MCP

* **Report queries:** `buying_stage` is a `scope` field on every [Reports API](https://docs.surfacd.com/docs/reports-api.md) entity, taking `awareness`, `consideration` and `decision`, and a dimension on visibility, sources, narratives and queries. With the dimension in `dimensions`, `buying_stage` in `filters` picks rows. `GET /api/v1/projects/{project}/reports/values/buying_stage` lists the three stages with their labels.
* **AI assistants (MCP):** `run_report` takes the same `buying_stage` field and dimension. See [MCP for AI Assistants](https://docs.surfacd.com/docs/mcp.md).
* **Prompts:** every prompt from the API and from the MCP prompt tools (`list_prompts`, `get_prompt`) includes its `buying_stage` (`awareness`, `consideration` or `decision`). A prompt and the prompts asking it as personas always share one stage. A new prompt shows `consideration` until it's classified.
* **Changing a stage:** send `buying_stage` to `PATCH /api/v1/projects/{project}/prompts/{prompt}`, or to the MCP `update_prompt` tool. It works like picking the stage in the app: Surfacd won't reclassify the prompt afterwards, and changing it on a persona prompt changes it for its whole family. It needs the same access as changing a stage in the app, so a read-only API key and viewers can't do it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.