> ## 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.

# Personas

> See how AI answers change depending on who is asking, and track your visibility with each member of the buying committee.

AI answers change depending on who's asking. A CFO who asks for "the best spend management tool for a 200-person company" can get a different shortlist from an IT director asking about the same category. Personas let you track both: they show which brands AI recommends to each of your buyers, not just to an anonymous searcher.

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

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

## Why Personas Matter

B2B purchases are rarely made by one person. A buying committee might include a finance lead who signs off, an IT lead who checks security, and the team who will use the product every day. Each of them asks AI their own questions, framed by their own role, company and priorities.

Personas let you see:

* **Who AI recommends you to.** You might lead the shortlist for finance buyers but barely appear for technical evaluators.
* **Where competitors win.** A rival that trails you overall can still dominate with one persona.
* **How much framing matters.** Compare each persona against your Baseline to see whether stating who is asking helps or hurts you.

## Key Concepts

| Term | Meaning |
| - | - |
| Persona | A buyer you want AI to recommend you to, such as "Growth-stage CFO" or "IT Director" |
| Persona prompt | A prompt asked from one persona's point of view. It has the same words as the prompt you wrote, and it's a prompt of its own |
| Baseline | Your prompts asked without a persona: how AI answers anyone. It's the reference you compare each persona against, and it's always listed first |

You write each prompt once, plainly, and choose the personas to ask it as. Surfacd keeps asking the prompt as you wrote it, which is your Baseline, and also asks it once as each persona you pick. Personas belong to a project, so each project has its own set.

> [!WARNING]
>
> **Each persona you ask a prompt as adds a prompt.** Asking 20 prompts as 3 personas adds 60 prompts to your project. They count towards the project's prompt limit and use credits on every run, like any other prompt. See [Prompt Limits and Credits](#prompt-limits-and-credits) before you add personas to many prompts.

## Getting Started

**1. Add your personas**

Open **Manage Personas** under Settings in the project sidebar and click **Add personas**. Fill in the form for one buyer: a name and at least one job title are required. See [Adding a Persona](#adding-a-persona).

**2. Choose the prompts to ask as each persona**

On the **Prompts** page, select prompts and choose **Manage personas › Add personas**. You can also pick **Personas** when you add new prompts. See [Asking Prompts as Personas](#asking-prompts-as-personas).

**3. Compare your buyers**

After the next data collection run, open **Visibility** and choose the **Personas** tab, or look at the **Buying journey** section on the Overview. See [Comparing Personas](#comparing-personas).

## Adding a Persona

On **Manage Personas**, click **Add personas**. A blank form opens, and you describe the buyer yourself. Surfacd doesn't suggest personas or add any for you. Save the form with **Add persona**, then click **Add personas** again for the next one.

![The Add persona form with a name, two job titles, a seniority, two company sizes and motivators filled in](https://mintcdn.com/surfacd/mbMAKpBDuamf4guS/images/personas/add-persona-form.png?fit=max\&auto=format\&n=mbMAKpBDuamf4guS\&q=85\&s=1111925664c633daa93cb1c477cbc21c)

The Add persona form. The count under each field shows how much of its limit you've used.

| Field | What it captures | Limit | Example |
| - | - | - | - |
| Name (required) | The short label shown in filters and reports. It must be unique in the project | 100 characters | Growth-stage CFO |
| Job titles (required) | The titles they typically hold. Press Enter or a comma after each one | Up to 8, 100 characters each | Chief Financial Officer, VP Finance |
| Seniority | Pick from the suggestions or type your own | Up to 8 | C-suite |
| Company size | One or more employee-count bands | Any of the 8 bands | 51–200 employees, 201–500 employees |
| Industry | Pick from the suggestions or type your own | Up to 8 | Software & SaaS |
| Motivators | What they're trying to achieve, and why they look for a solution | 255 characters | Wants to close the books faster and see spend in real time |
| Pain points | What gets in their way today | 255 characters | Forecasts live in disconnected spreadsheets |

Each field shows a count such as `105/255` under it, which turns red when the field is full.

### Generate with AI

Not sure what to write for motivators or pain points? Once the form has a name and a job title, click **Generate with AI** under either field. Surfacd drafts one or two short sentences from the details you've entered and your brand. **Generate with AI** only drafts these two fields. It doesn't create personas or fill in the rest of the form.

* An empty field takes the draft straight away.
* If you've already written something, the draft appears below it. Choose **Replace mine** or **Keep mine**.

Nothing is saved until you click **Add persona**. Saving a persona doesn't add prompts or start a data collection run.

> [!TIP]
>
> Keep motivators and pain points specific and short. "Wants to close the books in under five days" tells AI more about the buyer than "wants efficiency".

### How a persona changes what AI is asked

When Surfacd asks a persona prompt, it puts that buyer's perspective in front of your words, so AI knows who is asking. Surfacd writes that perspective from the persona's details each time you save the persona. You don't see or edit it, and your prompts always show your own words.

| Asked as | Prompt you see | What AI is asked |
| - | - | - |
| Baseline | "Which spend management tools should I shortlist?" | "Which spend management tools should I shortlist?" |
| Growth-stage CFO | "Which spend management tools should I shortlist?" | "I'm the CFO of a 200-person SaaS company. Which spend management tools should I shortlist?" |

Write every prompt plainly, even one you'll ask as personas. Don't start it with "As a CFO…": the persona's perspective is added when it's asked.

A prompt can be up to 475 characters. That leaves room for the whole perspective, so a persona prompt is always asked with the persona's full perspective and your full prompt.

## Managing Personas

**Manage Personas** lists every persona in the project, with its job titles, its profile and how many prompts are asked as it. The count beside **Add personas** shows how many of the project's 10 personas you've used. Select a prompt count to open the Prompts page with just that persona's prompts, grouped by persona.

![The Manage Personas page listing three personas with their profiles and prompt counts](https://mintcdn.com/surfacd/mbMAKpBDuamf4guS/images/personas/manage-personas.png?fit=max\&auto=format\&n=mbMAKpBDuamf4guS\&q=85\&s=5079176e9a5778b19192ea6682085c41)

Manage Personas, under Settings in the project sidebar

* **Edit:** click a persona's row, or its pencil icon, to change its name or details. Its prompts keep their words and their history, and are asked with the updated details from the next run.
* **Delete:** click the bin icon, then **Delete persona and prompts** (**Delete persona** if it has none). This deletes the persona and its persona prompts, and their answers leave every report. The prompts they were asked from are kept, and keep being asked as your Baseline. This can't be undone.

A persona is either in use or deleted. To stop asking just some prompts as a persona, [remove it from those prompts](#prompts-you-already-track) instead.

> [!NOTE]
>
> A project can have up to **10 personas**. When you reach the limit, **Add personas** is disabled: delete a persona to add another. Persona names must be unique within a project, ignoring letter case. Adding a persona with the name of one you deleted creates a new persona: the deleted one's answers don't come back.

### Who can manage personas

What you can change depends on your [team role](https://docs.surfacd.com/docs/team-settings.md#members). Owners can do everything.

| Action | Viewer | Member | Admin |
| - | - | - | - |
| See personas and filter reports by them | ✓ | ✓ | ✓ |
| Add, edit and delete personas | | ✓ | ✓ |
| Add, replace or remove the personas a prompt is asked as | | ✓ | ✓ |

## Asking Prompts as Personas

You choose which prompts each persona asks. Surfacd never asks your existing prompts as a persona automatically: the answers you've collected so far weren't asked as any buyer, so they stay as your Baseline.

### Prompts you already track

On the **Prompts** page, select prompts, open **Manage personas** in the selection bar at the bottom of the page and pick the personas. The menu appears once the project has a persona, and you can select up to 100 prompts at a time.

![The Prompts page with two prompts selected and the Manage personas menu open, showing Add personas, Replace personas and Remove personas](https://mintcdn.com/surfacd/mbMAKpBDuamf4guS/images/personas/manage-personas-bulk-action.png?fit=max\&auto=format\&n=mbMAKpBDuamf4guS\&q=85\&s=75abcac1bd4a021e0b33706da17d8150)

Select prompts, then choose Manage personas in the selection bar

| Action | What it does | Prompt limit and credits |
| - | - | - |
| **Add personas** | Also asks each selected prompt as the personas you pick. Personas it's already asked as stay as they are | Adds one prompt per prompt and new persona |
| **Replace personas** | Asks each selected prompt as exactly the personas you pick, and deletes its persona prompts for any other | Counts only the prompts it adds beyond the ones it deletes, so a one-for-one swap fits even at your limit |
| **Remove personas** | Stops asking each selected prompt as the personas you pick by deleting those persona prompts | Frees room. It's never refused |

Removing a persona from a prompt, by **Remove personas**, **Replace personas** or by deleting the persona prompt, deletes that persona prompt, and its answers leave every report. If you add the persona to the prompt again later, it starts with no history.

If adding or replacing personas would go over your prompt limit or your credits, nothing changes and the dialog tells you why.

### New prompts

When you [add prompts manually](https://docs.surfacd.com/docs/adding-prompts.md#manual-entry), pick one or more **Personas**. Each prompt is added once without a persona, as your Baseline, and once as each persona you picked. If a prompt is already tracked, Surfacd keeps it and asks it as the personas you picked too. The **Personas** field shows to team members who can manage personas. File import and suggested prompts always add prompts without a persona, and you can add personas to them afterwards.

### Seeing persona prompts

The Prompts page keeps a prompt and its persona prompts together:

* **As a list, or by topic, country or buying stage,** each prompt shows once, with the personas it's asked as in the **Persona** column. Its numbers include every answer, asked as written and as each persona. Filter by a persona to see only that persona's answers.
* **By persona,** each persona lists its own prompts, with their own numbers. The Baseline is listed first.
* **Open a prompt** and choose the **Personas** tab to compare how it does as your Baseline and as each persona.
* **Export** the prompts list to get each prompt and each of its persona prompts on a row of its own, with a **Persona** column ("No persona" for the prompt as written), a **Buying stage** column and each row's own numbers. The rows of a prompt add up to its answers and mentions on the page, so you can pivot the spreadsheet by persona.

A prompt and its persona prompts move together. Deactivating, reactivating or deleting a prompt does the same to its persona prompts, and changing its topic, tags or [buying stage](https://docs.surfacd.com/docs/buying-stages.md) changes theirs too. A persona prompt has no status of its own: it's active while its prompt is, and comes back when its prompt is reactivated. To stop asking a prompt as one persona, delete that persona prompt, which you can do while it's active. A persona prompt's persona can't be changed: remove the persona and add another instead.

## Prompt Limits and Credits

Every persona prompt is a prompt of its own. Surfacd checks and charges for it exactly as it does for any prompt:

* **Prompt limit:** each active persona prompt counts as one prompt towards the project's [prompt limit](https://docs.surfacd.com/docs/adding-prompts.md#prompt-limits).
* **Credits:** each active persona prompt is checked on every platform in every run, so it uses credits like any prompt. See [How Credits Work](https://docs.surfacd.com/docs/how-credits-work.md).
* **Before anything changes,** Surfacd counts the persona prompts a request would add. If they would take the project over its prompt limit, or need more credits than your team has available, nothing is added and you see why.

Persona prompts of an inactive prompt don't count towards the limit or use credits, and neither do deleted ones.

### Worked example

You track 20 prompts on 4 platforms (1 credit each), checked weekly. You ask all 20 as 3 personas:

| | Before | After |
| - | - | - |
| Baseline prompts | 20 | 20 |
| Persona prompts | 0 | 20 × 3 = **60** |
| Active prompts (counted towards the prompt limit) | 20 | **80** |
| Credits per run (prompts × 4 platforms) | 80 | **320** |
| Credits reserved per month (weekly: runs × 5) | 400 | **1,600** |

Asking those prompts as personas quadruples the project's prompts and its credits. On a daily schedule the monthly reservation would grow from 2,400 to 9,600 credits.

> [!TIP]
>
> To see how much room you have, compare the project's active prompts with its prompt limit, and check your credits in [Usage](https://docs.surfacd.com/docs/usage-billing.md). Then work out the cost first: **prompts selected × personas picked = prompts added**.

## Comparing Personas

Once a persona has asked prompts, the new version compares your buyers side by side.

### Visibility › Personas

The **Personas** tab on Visibility shows your visibility for the Baseline and each persona over time, ranks them with the Baseline pinned first as the reference, and shows the brands AI names most for each.

![The Personas view on Visibility with a chart of each persona over time and a persona ranking table led by the Baseline](https://mintcdn.com/surfacd/mbMAKpBDuamf4guS/images/personas/personas-view.png?fit=max\&auto=format\&n=mbMAKpBDuamf4guS\&q=85\&s=db03cc01513792e1c8847941a7e884bb)

Visibility › Personas: each persona over time and ranked, with the Baseline first

Below the ranking, **Persona breakdown** shows each persona by [buying stage](https://docs.surfacd.com/docs/buying-stages.md) by default, so you can see where each buyer drops off. You can compare personas by platform, topic, country, tag or brand instead. Until a persona has asked prompts, the tab explains what personas add and links to **Manage Personas**.

### Elsewhere in the app

* **Visibility › Overview › Buying journey** shows your visibility at each buying stage as a funnel, and each persona's visibility at awareness, consideration and decision beside it. See [The Buying Journey](https://docs.surfacd.com/docs/buying-stages.md#the-buying-journey).
* **Visibility › Overview:** choose **Personas** in the **Compare** menu to rank you as each persona asks, or pick Personas as the rows or columns of the **Breakdown**.
* **Prompts:** choose **By persona** to group your prompts under each persona, with the Baseline first.
* **Details:** select a persona anywhere it's listed to open its details: its visibility over time, and how it breaks down by brand, platform, topic and prompt. The details of a brand, platform, topic, country or cited site also have a **Personas** tab.

### Filtering by persona

Once your project has a persona, the filter bar includes a **Personas** filter. It applies to Overview, Visibility, Answers, Sources, Prompts and Reputation. Select one or more personas to see results for just those buyers, or select **Baseline** to see only the prompts asked without a persona. A persona that hasn't asked any prompts yet shows as "No prompts yet" and can't be selected.

Like other filters, your persona selection carries across pages, can be kept in a saved filter and applies to exports.

## Personas, Topics and Tags

Personas sit alongside topics and tags, but they do a different job. Topics and tags describe **what** a prompt is about. A persona describes **who** is asking, and changes what AI is asked.

| | Topics | Tags | Personas |
| - | - | - | - |
| **Describes** | What the question is about | Any label you choose | Who is asking |
| **Per prompt** | One | Several | Several: the prompt is asked once as each, as a prompt of its own |
| **Adds prompts** | No | No | Yes, one per persona |
| **Has a profile** | Name and description | Name and colour | Job titles, seniority, company size, industry, motivators and pain points |
| **Created** | AI-generated during setup, editable anytime | Created as you need them | Written by you, editable anytime |
| **Prompts without one** | Uncategorized | Untagged | Baseline |
| **Example** | "Expense Management" | "High Priority" | "Growth-stage CFO" |

See [Topics & Tags](https://docs.surfacd.com/docs/tags-organisation.md) for more on organising your prompts.

## Tips for Adding Personas

> [card] Start with the buyers who decide
>
> Begin with the people who sign off or shortlist, such as the budget holder and the technical evaluator. Add others once you've seen how these two compare with your Baseline.

> [card] Keep it to two to four
>
> Each persona adds a prompt for every prompt it asks, so a few well-chosen personas tell you more than ten thin ones. You can have up to 10 per project.

> [card] Read everything against the Baseline
>
> The Baseline is how AI answers when it doesn't know who's asking. A persona is only interesting where it differs from it, so compare each persona with the Baseline rather than with each other.

> [card] Write prompts plainly
>
> Surfacd adds the buyer's perspective when it asks a persona prompt, so leave "As a CFO…" out of the prompt itself. Otherwise your Baseline asks as a CFO too.

> [card] Start with a subset of prompts
>
> Add personas to the 10 to 20 prompts that matter most, such as those closest to a purchase, rather than to every prompt. Expand once you know the cost and the value.

> [card] Keep profiles current
>
> Update motivators and pain points when your positioning or target customer changes. Persona prompts pick up the change from the next run.

> [!NOTE]
>
> Persona prompts take effect from the next data collection run. Give each persona a few runs before you draw conclusions, as with any new prompt.

## API & MCP

Personas are available through the [API](https://docs.surfacd.com/api-reference) and to [connected AI assistants](https://docs.surfacd.com/docs/mcp.md) as well as in the app. The API and MCP call the Baseline `no_persona`, labelled "No persona", so use `no_persona` wherever the app says **Baseline**.

* **Manage personas (API):** list, create, read, update and delete a project's personas. The same limits apply as in the app: a name (100 characters) and at least one job title are required, lists take up to 8 items, `motivators` and `pain_points` take up to 255 characters, and a project can have up to 10 personas. Deleting a persona deletes its persona prompts too, and their answers leave every report.
* **Prompts:** every prompt includes its `persona` (UUID and name, or `null` for a Baseline prompt), and a persona prompt includes `source_prompt_uuid`, the prompt it asks as a persona. When you create a prompt, list `personas` (UUIDs or names, ignoring letter case) to ask it as each of them too: the prompt is created without a persona, plus one prompt per persona, and they all count towards your prompt limit and credits. Sending a prompt you already track adds the personas to it. A prompt's own persona can't be changed afterwards, but you can change the personas it's asked as (see below). A persona prompt has no status of its own: setting its `status` is refused with a 422, and `DELETE /api/v1/projects/{project}/prompts/{prompt}` deletes it even while it's active, which removes that persona from the prompt. Other prompts must be inactive before they can be deleted. Changing a persona prompt's topic or tags changes them for its whole family, as in the app. Adding personas needs the same access as managing personas, so a read-only API key can't do it.
* **See and change the personas one prompt is asked as:** a prompt without a persona includes `persona_prompts`, its persona prompts with each one's `uuid` and `persona` (UUID and name), ordered by persona name; it's empty when the prompt is asked as no persona and `null` on a persona prompt. `PATCH /api/v1/projects/{project}/prompts/{prompt}` takes `add_personas` and `remove_personas` (persona UUIDs or names) to change them, alongside `topic`, `buying_stage` and `status`. There is no replace: remove some personas and add others in the same request. Sending a persona prompt's UUID changes its family, but a persona prompt can't remove its own persona: delete it instead. Every field is checked before anything changes, and nothing changes when the personas added don't fit your prompt limit or credits. Only an active prompt can be asked as personas, so activate a prompt in its own request first.
* **Add, replace or remove personas on many prompts:** `PATCH /api/v1/projects/{project}/prompts/personas` takes an `action` (`add`, `replace` or `remove`), up to 100 prompt UUIDs in `prompts` and persona UUIDs or names in `personas`, and works like the bulk actions on the Prompts page. Selecting a persona prompt selects the prompt it asks. Removing deletes the persona prompts, and replacing deletes the ones it drops; their answers leave every report. Adding and replacing change nothing if the prompts don't fit your prompt limit or credits. The response lists every prompt of the prompts you changed, with their remaining persona prompts.
* **Filter reports:** [report queries](https://docs.surfacd.com/docs/reports-api.md) take `persona_uuid` (persona UUIDs, or `no_persona` for the Baseline) and `persona` (names) in `scope`, and group by the `persona` dimension on visibility and sources. The older reporting endpoints and the MCP report tools take a `personas` filter with the same values.
* **Compare and explain:** matrix analysis accepts `persona` as a row or column dimension, and the "why did visibility change?" breakdown includes personas alongside platforms, countries and topics once the project has personas.
* **AI assistants (MCP):** the `list_personas` tool lets an assistant see your personas before it filters or compares by them, or creates prompts asked as them (`personas` on `create_prompts`). `create_persona`, `update_persona` and `delete_persona` manage personas, and `bulk_update_prompt_personas` adds, replaces or removes them on prompts you already track. `update_prompt` takes `add_personas` and `remove_personas` for one prompt, and `get_prompt` and `list_prompts` show `persona_prompts`. `delete_prompt` deletes a single persona prompt, even while it's active. Deleting a persona, or removing it from prompts, deletes those persona prompts and their answers, so assistants that ask before taking actions ask first.

Try asking a connected assistant: *"Which brands does ChatGPT recommend to our Growth-stage CFO persona?"* or *"Why did visibility drop for the IT Director persona last week?"*

See [API Routing](https://docs.surfacd.com/docs/api-routing.md#discovering-identifiers) for how filters use public identifiers.


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