# Archive or Restore Project
Source: https://docs.surfacd.com/api-reference/projects/archive-or-restore-project
/openapi.json patch /api/v1/projects/{project}/archive
Archives a project, or restores it when `archived` is `false`. Archiving releases the project's reserved credits. Restoring resumes collection at the project's stored frequency and re-reserves the credits that schedule needs; if the team lacks sufficient available credits the restore is rejected with a `422` and no change is made.
# Create Project
Source: https://docs.surfacd.com/api-reference/projects/create-project
/openapi.json post /api/v1/projects
Creates a project for the current team, with its primary brand and the set of services (AI platforms) to monitor. The brand domain is normalised (protocol, `www`, and path are stripped).
# Create Project (team-scoped)
Source: https://docs.surfacd.com/api-reference/projects/create-project-team-scoped
/openapi.json post /api/v1/teams/{teamUuid}/projects
Team-scoped variant of the projects endpoint; identical contract with the team resolved from the path instead of the token's default team.
# Delete Project
Source: https://docs.surfacd.com/api-reference/projects/delete-project
/openapi.json delete /api/v1/projects/{project}
Soft-deletes a project. The project must be archived first: deletion is the exit from the archived state, not a shortcut from active. Deleting a project that is not archived is rejected with a `422` and no change is made; archive it via `PATCH /projects/{project}/archive` first.
# List Projects
Source: https://docs.surfacd.com/api-reference/projects/list-projects
/openapi.json get /api/v1/projects
Returns paginated projects for the current team. Excludes archived projects by default; pass `include_archived=1` to include them.
# List Projects (team-scoped)
Source: https://docs.surfacd.com/api-reference/projects/list-projects-team-scoped
/openapi.json get /api/v1/teams/{teamUuid}/projects
Team-scoped variant of the projects endpoint; identical contract with the team resolved from the path instead of the token's default team.
# Manage Project Sharing
Source: https://docs.surfacd.com/api-reference/projects/manage-project-sharing
/openapi.json patch /api/v1/projects/{project}/share
Manages a project's public share link. Send any combination of: `enabled` to turn sharing on/off, `password` to set or clear (null) a password, and `refresh_token` to rotate the share token (invalidating the previous link). Returns the current share state, including the share URL when sharing is enabled. The password itself is never returned.
# Promote Pitch Project
Source: https://docs.surfacd.com/api-reference/projects/promote-pitch-project
/openapi.json patch /api/v1/projects/{project}/promote
Promotes an ended pitch project to an ongoing standard project at the given cadence, lifting the pitch limits and reserving the credits the new schedule needs. Rejected with a 422 if the pitch window is still open, the team's active-project limit is reached, or there are insufficient credits; no change is made.
# Show Project
Source: https://docs.surfacd.com/api-reference/projects/show-project
/openapi.json get /api/v1/projects/{project}
Returns a single project for the current team, including primary brand, default country, and enabled services. Returns 404 if the project does not belong to the current team.
# Update Project
Source: https://docs.surfacd.com/api-reference/projects/update-project
/openapi.json patch /api/v1/projects/{project}
Partially updates a project. Only the fields present in the request body are changed. Services are matched by UUID or provider slug; supplying `services` replaces the monitored set. Changing the monitored services on a scheduled project triggers a new data collection run (which consumes credits). To update the primary brand, include `primary_brand.name`.
# Create Prompts
Source: https://docs.surfacd.com/api-reference/prompts/create-prompts
/openapi.json post /api/v1/projects/{project}/prompts
Creates one or more prompts on a project.
**Side effects: this is not a passive write.**
- Adding new active prompts normally **starts a data collection run**, which **consumes credits**. Exception: projects on a manual schedule do not auto-run after their first run; for those you must request a run separately.
- A **keyword** and **search volume** are generated automatically for each new prompt by the pipeline; you cannot supply them.
Duplicates of existing prompts (same text + country) are not re-created: an inactive duplicate is reactivated, and tag/topic changes are merged onto the existing prompt. New prompts are created with status `active`. Requests are rejected when they would exceed the project's prompt limit or the team's available credits.
# Delete Prompt
Source: https://docs.surfacd.com/api-reference/prompts/delete-prompt
/openapi.json delete /api/v1/projects/{project}/prompts/{prompt}
Deletes an inactive prompt, removing it and its history from reports, and recalculates the project's reserved credits. Only inactive prompts can be deleted: set an active prompt's `status` to `inactive` first, which stops collection but keeps its history in reports. Returns 422 if the prompt is still active, and 404 if the prompt's project does not belong to the current team.
# List Prompts
Source: https://docs.surfacd.com/api-reference/prompts/list-prompts
/openapi.json get /api/v1/projects/{project}/prompts
Returns paginated prompts for a project in the current team. Returns 404 if the project does not belong to the current team.
# Show Prompt
Source: https://docs.surfacd.com/api-reference/prompts/show-prompt
/openapi.json get /api/v1/projects/{project}/prompts/{prompt}
Returns a single prompt by UUID. Returns 404 if the prompt's project does not belong to the current team.
# Update Prompt
Source: https://docs.surfacd.com/api-reference/prompts/update-prompt
/openapi.json patch /api/v1/projects/{project}/prompts/{prompt}
Partially updates a prompt. Only the fields present are applied. `status` toggles between `active` and `inactive`: deactivating stops data collection and releases the prompt's reserved credits while keeping its history in reports; activating a prompt is subject to the project's prompt limit and the team's available credits. Pass `topic: null` to clear the topic. Keyword and search volume are pipeline-generated and cannot be set.
# Update Prompt Tags
Source: https://docs.surfacd.com/api-reference/prompts/update-prompt-tags
/openapi.json patch /api/v1/projects/{project}/prompts/tags
Bulk-updates tags across one or more of a project's prompts. Each entry targets a prompt by UUID and either replaces its tags wholesale (`sync`) or applies incremental changes (`add` / `remove`). `sync` cannot be combined with `add`/`remove`, and each entry must specify at least one of the three. Tags are referenced by UUID and must already exist on the project; use `/api/v1/projects/{project}/tags` to create or list them. The whole request is applied atomically.
# List available countries
Source: https://docs.surfacd.com/api-reference/reference/list-available-countries
/openapi.json get /api/v1/countries
Returns the active countries a project can target, ordered by name. Use a returned `code` as the `default_country_code` when creating a project or as a prompt's `country_code`.
# List available platforms
Source: https://docs.surfacd.com/api-reference/reference/list-available-platforms
/openapi.json get /api/v1/platforms
Returns the active AI platforms a project can run against, ordered by display name. Use the returned `provider` value in reporting `services` filters. For project service selection, send either the returned `provider` or `uuid`.
# List Brands
Source: https://docs.surfacd.com/api-reference/reference/list-brands
/openapi.json get /api/v1/projects/{project}/brands
Returns the project brands. Use the returned `uuid` values in `brands` reporting filters.
# List domain categories
Source: https://docs.surfacd.com/api-reference/reference/list-domain-categories
/openapi.json get /api/v1/domain-categories
Returns domain category enum values that can be passed in `categories` reporting filters.
# List Topics
Source: https://docs.surfacd.com/api-reference/reference/list-topics
/openapi.json get /api/v1/projects/{project}/topics
Returns the project topics. Use a returned `uuid` or `name` in `topics` reporting filters (names are case-insensitive). Topic creation is handled through prompt creation/update workflows.
# Brand Mentions
Source: https://docs.surfacd.com/api-reference/reporting/brand-mentions
/openapi.json get /api/v1/projects/{project}/mentions
Returns paginated brand mentions matched within the requested date range. Supports filtering by brand, AI service, country, tag, topic, prompt, rank range, sentiment, and free-text search across snippets.
# Brand Rankings
Source: https://docs.surfacd.com/api-reference/reporting/brand-rankings
/openapi.json get /api/v1/projects/{project}/brand-rankings
Returns paginated brand rankings within a date range, with optional filters for brands, tags, services, countries, prompts, topics, and brand search. Each row includes visibility, mention-weighted sentiment score (0–100 Net Sentiment Index), mentions, and average position. Use `brands` with `only_brand` or `always_include_brand` to pin a specific brand.
# Matrix Analysis
Source: https://docs.surfacd.com/api-reference/reporting/matrix-analysis
/openapi.json get /api/v1/projects/{project}/matrix-analysis
Returns a metric (visibility, mentions, industry rank, or average position) broken out across two public dimensions. Row, column, and cell identifiers use the same public identifiers as filters: provider strings, country codes, enum values, UUIDs, or stable sentinels.
# Sources (Category Distribution)
Source: https://docs.surfacd.com/api-reference/reporting/sources-category-distribution
/openapi.json get /api/v1/projects/{project}/sources-data/category-distribution
Returns the distribution of cited source categories for a single brand across the requested date range, along with total source and response counts.
# Sources (Domains)
Source: https://docs.surfacd.com/api-reference/reporting/sources-domains
/openapi.json get /api/v1/projects/{project}/sources-data/domains
Paginated list of domains cited by AI responses for the project across the date range. Each row includes citation count, rank, optional category, and comparison fields versus the previous period.
# Sources (Hostnames)
Source: https://docs.surfacd.com/api-reference/reporting/sources-hostnames
/openapi.json get /api/v1/projects/{project}/sources-data/hostnames
Paginated list of hostnames (e.g. `blog.example.com`) cited by AI responses for the project across the date range.
# Sources (URLs)
Source: https://docs.surfacd.com/api-reference/reporting/sources-urls
/openapi.json get /api/v1/projects/{project}/sources-data/urls
Paginated list of individual URLs cited by AI responses for the project. Supply either `domain` or `hostname` to scope to citations under that source; if both are sent, `hostname` wins.
# Visibility Change Decomposition
Source: https://docs.surfacd.com/api-reference/reporting/visibility-change-decomposition
/openapi.json get /api/v1/projects/{project}/visibility-decomposition
Explains why the brand's visibility score changed between the selected period and the previous period of equal length. The comparison window is derived automatically and echoed back as `comparison_start_date` / `comparison_end_date`.
The change is decomposed across three dimensions - services, countries and topics - each of which partitions the analysed response set. Within a dimension, every segment carries a `contribution`: the visibility-point effect (on the 0-1 scale) of that segment's own mention-rate movement, weighted by the segment's share of responses. The dimension's `mix_contribution` captures change caused by a shift in where responses were collected (added platforms, new prompts, different response volumes) rather than by mention-rate movement. For every dimension, the segment contributions plus `mix_contribution` sum exactly to `after_visibility - before_visibility`.
`within_noise: true` marks segments whose sample is too small (fewer than 30 responses in either period) or whose movement sits inside the 95% confidence interval for the rate difference; treat those movements as inconclusive.
Segment `id`s use the same public identifiers as the filter parameters (service providers, country codes, topic UUIDs or `no_topic`), so drilling down is iterative: pass a segment's `id` back as the matching filter (`services`, `countries`, `topics`) and call the endpoint again to decompose that slice across the remaining dimensions. Use `GET /api/v1/projects/{project}/mentions` with the same filters to retrieve concrete example responses.
When every partitioning dimension has been pinned to a single segment, pass `include_prompts=true` to reach the final level: the individual prompts that moved the slice.
# Visibility Over Time
Source: https://docs.surfacd.com/api-reference/reporting/visibility-over-time
/openapi.json get /api/v1/projects/{project}/visibility-over-time
Returns a per-brand series of visibility and sentiment metrics across a date range, optionally rolled up to weekly or monthly buckets. Use `brands` with brand UUIDs to select the series.
# Get Narrative
Source: https://docs.surfacd.com/api-reference/reputation/get-narrative
/openapi.json get /api/v1/projects/{project}/reputation/narratives/{narrative}
A single narrative with its windowed summary, per-platform sentiment split, and sibling narratives sharing its theme.
# Get Response
Source: https://docs.surfacd.com/api-reference/reputation/get-response
/openapi.json get /api/v1/projects/{project}/reputation/responses/{response}
Full detail for a single AI response: the response record, its prompt (with target country), the platform, cited sources, and any brand mentions.
# Get Theme
Source: https://docs.surfacd.com/api-reference/reputation/get-theme
/openapi.json get /api/v1/projects/{project}/reputation/themes/{theme}
A single theme with its narratives, per-platform sentiment split, and trajectory across the date range.
# List Narratives
Source: https://docs.surfacd.com/api-reference/reputation/list-narratives
/openapi.json get /api/v1/projects/{project}/reputation/narratives
Paginated list of reputation narratives (recurring storylines) for the project across the date range.
# List Responses
Source: https://docs.surfacd.com/api-reference/reputation/list-responses
/openapi.json get /api/v1/projects/{project}/reputation/responses
Paginated list of AI responses scoped to a narrative or theme (a theme expands to its narratives' mentions), windowed to the date range.
# List Themes
Source: https://docs.surfacd.com/api-reference/reputation/list-themes
/openapi.json get /api/v1/projects/{project}/reputation/themes
Paginated list of reputation themes (clusters of related narratives) for the project across the date range.
# Reputation Overview
Source: https://docs.surfacd.com/api-reference/reputation/reputation-overview
/openapi.json get /api/v1/projects/{project}/reputation/overview
Headline reputation KPIs for the project across the date range, with comparison values versus the equal-length previous period.
# Reputation Sources (Domains)
Source: https://docs.surfacd.com/api-reference/reputation/reputation-sources-domains
/openapi.json get /api/v1/projects/{project}/reputation/sources/domains
Paginated list of domains cited by the AI responses behind a narrative, theme, or brand, across the date range.
# Reputation Sources (Prompts)
Source: https://docs.surfacd.com/api-reference/reputation/reputation-sources-prompts
/openapi.json get /api/v1/projects/{project}/reputation/sources/prompts
Paginated list of prompts whose AI responses cited a specific URL, within a narrative, theme, or brand scope, across the date range.
# Reputation Sources (URLs)
Source: https://docs.surfacd.com/api-reference/reputation/reputation-sources-urls
/openapi.json get /api/v1/projects/{project}/reputation/sources/urls
Paginated list of individual URLs cited by the AI responses behind a narrative, theme, or brand. Supply either `domain` or `hostname` to scope to citations under that source; if both are sent, `hostname` wins.
# Sentiment by Platform
Source: https://docs.surfacd.com/api-reference/reputation/sentiment-by-platform
/openapi.json get /api/v1/projects/{project}/reputation/sentiment-by-model
Per-platform sentiment distribution and Net Sentiment Index for the project across the date range.
# Sentiment Over Time
Source: https://docs.surfacd.com/api-reference/reputation/sentiment-over-time
/openapi.json get /api/v1/projects/{project}/reputation/sentiment-series
Daily positive/neutral/negative mention counts for the project across the date range, on a contiguous day axis.
# Create Tag
Source: https://docs.surfacd.com/api-reference/tags/create-tag
/openapi.json post /api/v1/projects/{project}/tags
Creates a tag on the project and returns it with its public UUID.
# Delete Tag
Source: https://docs.surfacd.com/api-reference/tags/delete-tag
/openapi.json delete /api/v1/projects/{project}/tags/{tag}
Deletes a project tag and detaches it from prompts.
# List Tags
Source: https://docs.surfacd.com/api-reference/tags/list-tags
/openapi.json get /api/v1/projects/{project}/tags
Returns the project tags. Use a returned `uuid` for prompt tag assignment. Reporting filters accept a tag `uuid` or `name` (names are case-insensitive).
# Show Tag
Source: https://docs.surfacd.com/api-reference/tags/show-tag
/openapi.json get /api/v1/projects/{project}/tags/{tag}
# Update Tag
Source: https://docs.surfacd.com/api-reference/tags/update-tag
/openapi.json patch /api/v1/projects/{project}/tags/{tag}
# Get Team Settings
Source: https://docs.surfacd.com/api-reference/team/get-team-settings
/openapi.json get /api/v1/teams/{teamUuid}
Returns settings for the current team, plus its plan name, display prices, and the features included on that plan. The plan is read-only and cannot be changed through the API.
# Get Team Settings
Source: https://docs.surfacd.com/api-reference/team/get-team-settings-1
/openapi.json get /api/v1/team
Returns settings for the current team, plus its plan name, display prices, and the features included on that plan. The plan is read-only and cannot be changed through the API. Operates on the token's default team; use the /teams/{teamUuid} variant to target a specific team.
# Get Team Usage
Source: https://docs.surfacd.com/api-reference/team/get-team-usage
/openapi.json get /api/v1/teams/{teamUuid}/usage
Returns the current team's credit summary plus a per-project breakdown of scheduled credit usage. The breakdown lists projects that currently reserve credits or have consumed one-off credits this calendar month.
# Get Team Usage
Source: https://docs.surfacd.com/api-reference/team/get-team-usage-1
/openapi.json get /api/v1/team/usage
Returns the current team's credit summary plus a per-project breakdown of scheduled credit usage. The breakdown lists projects that currently reserve credits or have consumed one-off credits this calendar month. Operates on the token's default team; use the /teams/{teamUuid} variant to target a specific team.
# Invite Team Member
Source: https://docs.surfacd.com/api-reference/team/invite-team-member
/openapi.json post /api/v1/teams/{teamUuid}/members
Invites a member to the current team by email. The member starts with `pending` status until they accept. If the email isn't a registered user yet, an account is created for them. Owner cannot be assigned via the API.
**Side effect:** the invitee is sent an invitation email.
# Invite Team Member
Source: https://docs.surfacd.com/api-reference/team/invite-team-member-1
/openapi.json post /api/v1/team/members
Invites a member to the current team by email. The member starts with `pending` status until they accept. If the email isn't a registered user yet, an account is created for them. Owner cannot be assigned via the API.
**Side effect:** the invitee is sent an invitation email. Operates on the token's default team; use the /teams/{teamUuid} variant to target a specific team.
# List Team Members
Source: https://docs.surfacd.com/api-reference/team/list-team-members
/openapi.json get /api/v1/teams/{teamUuid}/members
Returns all members of the current team, including those with a pending invitation.
# List Team Members
Source: https://docs.surfacd.com/api-reference/team/list-team-members-1
/openapi.json get /api/v1/team/members
Returns all members of the current team, including those with a pending invitation. Operates on the token's default team; use the /teams/{teamUuid} variant to target a specific team.
# List teams
Source: https://docs.surfacd.com/api-reference/team/list-teams
/openapi.json get /api/v1/teams
# Remove Team Member
Source: https://docs.surfacd.com/api-reference/team/remove-team-member
/openapi.json delete /api/v1/teams/{teamUuid}/members/{email}
Removes a member from the current team (revokes access or a pending invitation). The team owner cannot be removed.
# Remove Team Member
Source: https://docs.surfacd.com/api-reference/team/remove-team-member-1
/openapi.json delete /api/v1/team/members/{email}
Removes a member from the current team (revokes access or a pending invitation). The team owner cannot be removed. Operates on the token's default team; use the /teams/{teamUuid} variant to target a specific team.
# Show Team Member
Source: https://docs.surfacd.com/api-reference/team/show-team-member
/openapi.json get /api/v1/teams/{teamUuid}/members/{email}
Returns a single team member by email.
# Show Team Member
Source: https://docs.surfacd.com/api-reference/team/show-team-member-1
/openapi.json get /api/v1/team/members/{email}
Returns a single team member by email. Operates on the token's default team; use the /teams/{teamUuid} variant to target a specific team.
# Update Member Role
Source: https://docs.surfacd.com/api-reference/team/update-member-role
/openapi.json patch /api/v1/teams/{teamUuid}/members/{email}
Changes a member's role. The team owner's role cannot be changed, and Owner cannot be assigned (ownership is transferred through a separate flow).
# Update Member Role
Source: https://docs.surfacd.com/api-reference/team/update-member-role-1
/openapi.json patch /api/v1/team/members/{email}
Changes a member's role. The team owner's role cannot be changed, and Owner cannot be assigned (ownership is transferred through a separate flow). Operates on the token's default team; use the /teams/{teamUuid} variant to target a specific team.
# Changelog
Source: https://docs.surfacd.com/changelog
New features, improvements, and fixes in Surfacd, newest first.
## Members can now manage every part of a topic
Members could already create, rename and assign topics, but deleting one needed an Admin.
Members can now do all of it from **Manage Topics** or the Prompts page. Deleting a topic never
deletes prompts: any prompts still in it move to Uncategorized.
On the Prompts page, the selection toolbar now shows only the actions your role can use. If you
can assign tags but not create them, the tag picker lists your project's existing tags without
offering to create new ones. See [who can manage topics and tags](/docs/tags-organisation#who-can-manage-topics-and-tags)
for the full breakdown by role.
## Deactivate prompts and keep their history
Replacing a prompt used to mean deleting it, and deleting a prompt removed its history from
your reports. Select prompts on the Prompts tab and click **Deactivate** to stop collecting
them instead. Their topic, tags and past results stay in place, so you can see how a new
prompt performs against the one it replaced.
Deactivated prompts move to a new **Inactive** tab. From there you can reactivate a prompt to
start collecting again, or delete it to remove it and its history from your reports. Active prompts are now deactivated before
they can be deleted, so history is never removed by accident.
If you deactivate every prompt in a project, collection pauses but your reports stay
available. Collection resumes when you activate or add a prompt.
Through the API and MCP server, set a prompt's `status` to `inactive` to deactivate it. The same
rule applies there too: only inactive prompts can be deleted.
## Reputation dates now ignore deleted prompts
When you delete a prompt, its responses drop out of your reports. Reputation's first-seen
and last-seen dates now follow the same rule, on the Narratives and Themes lists, on each
detail page and through the API. The **Latest** sort on Narratives uses the same dates.
Related narratives on a narrative's detail page are also ranked using only responses from
prompts you still track.
## Introducing Reputation
Visibility tells you whether you appear in an AI answer. Reputation tells you what that
answer means. You can win the mention and still lose the customer if ChatGPT, Gemini or
Perplexity describe you poorly, and until now there was no way to see that at scale.
Reputation analyses the responses Surfacd already collects and surfaces the recurring
stories AI platforms tell about your brand. Narratives such as "praised for fast support"
or "criticised for pricing" are grouped into themes, scored for sentiment and tracked over
time, so you can see which stories are growing, which are fading, and which platforms are
driving them. Competitor views show how the same themes play out for the brands you are
measured against.
Reputation is included on every plan. Open a project, click **Reputation** in the sidebar
and enable it. Analysis starts with your next collection and there is nothing extra to
configure. It is in beta and free to use while it is.
## Faster Source Analysis
Source Analysis loads faster on projects with large source histories, including when opening a website's cited pages or exporting results.
## Download Rankings and Answers as a PDF or Markdown report
Until now the only way to take a report out of the app was a spreadsheet of the underlying rows. Rankings and Answers now also download as a formatted report: the charts, tables and every active filter laid out as a document you can share.
Choose **Export as PDF** for a branded, print-ready version, or **Export as Markdown** to paste the same report into an AI assistant and ask it to analyse or summarise your results. Each report includes a link that reopens the live page with the same filters applied.
Both live in the **Export** menu on the page, alongside the existing spreadsheet download.
## Manage your topics in one place
Topics group your prompts by theme, but until now you could only shape them while
editing prompts. The new Manage Topics page, under Manage Tags in the project sidebar,
shows every topic with its description, prompt count and creation date.
From here you can create a topic ahead of assigning prompts, rename one, or update its
description. Click a topic's prompt count to jump straight to its prompts.
Deleting is safe by design: you are asked to confirm first, and prompts are never
deleted with their topic. Any prompts still assigned move to Uncategorized, and the
confirmation tells you how many prompts that affects.
## See the searches AI ran before it answered
Open any answer from Mentions, the Dashboard or Reputation and a new Search Queries
section sits beside the sources. It shows every web search the platform issued while
building that answer, in the order it ran them, including operators such as `site:`
and quoted phrases.
Search-backed platforms often run several queries for one prompt. Seeing them tells you
which questions the AI actually asked, which competitor sites it went looking at, and
which regulations or terms it considered essential. Pages that rank for those searches
are what the AI reads before it answers.
Platforms that answer from their own knowledge run no searches, so the section stays
hidden for them. The queries are also returned by the response detail API endpoint and
the MCP response tool.
## In-app explanations for every metric
Every report now explains itself. Hover a column heading like Visibility Score, Avg.
Position or Citations, or the info icon beside a card, and a small panel tells you what
the number means and how to read it — with a concrete example, such as "If AI gave 100
answers and 40 mentioned the brand, visibility is 40%".
Bigger topics come with a short walkthrough video embedded right in the panel: creating
a project, adding prompts, organising with topics, comparing visibility over time,
tracking competitors, browsing answers, and the Analyse matrix. Where a docs page covers
the topic in depth, the panel links straight to it.
You will find these across the Dashboard, Rankings, Answers, Sources, Analyse,
Reputation, Prompts, project settings and team settings.
Reach out to [support@surfacd.com](mailto:support@surfacd.com) if you have any questions or feedback.
## Monitor your brand in Claude
Claude is available as an early-access platform. It is not included in plans by
default, so contact support to enable it for your team. Surfacd queries Claude with web
search switched on, so responses reflect both the model's knowledge and the pages it
cites.
Claude's data is significantly more expensive to collect than most platforms, so each
prompt check costs 30 credits rather than 1. The platform selector now shows a credit
badge next to any platform that costs more than the standard rate, and the credit estimate
for a project always reflects the real total.
Claude is monitored through the model provider's API rather than the consumer app, and
carries an **API** badge in the selector to make that clear.
## Filter API and MCP reports by tag or topic name
Every reporting and reputation endpoint in the public API, and every report tool in the
MCP server, now shares the same four filters: platforms, countries, tags and topics.
Tags and topics accept either a UUID or a name. Names are matched case-insensitively
within the project. Topics also accept `no_topic` to select prompts that have not been
assigned a topic.
Unknown values are rejected with a clear validation message rather than silently
ignored, so a typo in a tag name will not quietly return unfiltered data.
## Grok now monitored through its API
Grok is now monitored through the model provider's API, with an **API** badge in the
platform selector.
Because the way Grok is collected has changed, it has been deselected on every project
that had it enabled. Any credits reserved for Grok on scheduled projects have been
returned to your team. To keep monitoring Grok, open your project's platform settings and
select it again.
## Colour-code your tags
Pick a colour when you create a tag, whether that is from **Manage Tags** or by typing a
new tag name while adding prompts. Ten colours are available: grey, blue, cyan, purple,
pink, red, orange, yellow, green and teal.
Colours appear wherever tags do: on prompt rows, in tag dropdowns, in the bulk-tagging
tools and in report filter controls. Existing tags and tags created by CSV import show as
grey until you choose a colour from **Manage Tags**.
The public API returns a `color` field on every tag and accepts one when creating or
updating a tag.
## Save and reopen your favourite report views
Set up the filters you use most, then open the chevron next to the page name in the
breadcrumb and choose **Save current view**. The dialog shows exactly which filters will
be saved before you confirm.
Saved views are listed in the same menu. Views for the current page appear first, and
you can search across every page's views, rename them, or delete them.
Dates can be saved three ways: leave them out so the view uses whatever range you have
active, pin the exact dates, or choose a rolling range such as **Last 28 days** or
**Previous month** that resolves to fresh dates each time you apply it.
## Report filters and views now live in the link
Filters, selected tabs, sort orders, search terms and comparison sets on the reporting
pages are now stored in the page address. Copy the link and whoever opens it sees the same
view you do.
Only the settings that differ from the page default are added, so links stay short.
The browser back and forward buttons step through your filter changes, and reloading a
page no longer resets it.
This applies across Dashboard, Rankings, Mentions, Analyse, Sources, and the Reputation
pages.
## Sentiment score alongside visibility in Rankings and the Dashboard
Visibility tells you how often a brand appears. Sentiment tells you how it is described
when it does. Both now sit side by side.
In Brand Rankings, each brand has a **Sentiment Score** column with a colour band and a
trend against the previous period. The Rankings CSV export includes the same values.
On the Dashboard, the Industry Ranking card shows each brand's sentiment score, and the
visibility chart has a **Visibility / Sentiment** toggle so you can chart either metric
for every brand in the ranking. A period with no mentions has no sentiment to report, so
the line bridges the gap rather than dropping to zero.
The public API and MCP tools return the same `sentiment_score` and
`previous_sentiment_score` fields on brand rankings and visibility-over-time responses.
## Follow what's new in Surfacd
Improvements used to land quietly. Now every change that affects what you can see or
do in Surfacd gets written up here as it goes live.
Each entry explains what changed and why it matters, so you can tell at a glance
whether something is worth a second look.
Prefer updates to come to you? Subscribe to the RSS feed from the icon at the top of
the changelog page and pipe it into Slack, email, or your reader of choice.
# Adding Prompts
Source: https://docs.surfacd.com/docs/adding-prompts
Learn the different ways to add prompts to your project, from manual entry and file import to AI-generated suggestions.
Surfacd offers three ways to add prompts to your project. Navigate to your project's **Prompts** tab and click **+ Add Prompts** to get started.
## Manual Entry
Add prompts directly by typing them. This works well for specific questions you know your buyers ask, drawn from sales calls, customer feedback, or industry events.
* **Single Prompt**: add one prompt with a custom country and tag settings
* **Multiple Prompts**: bulk add, one per line, sharing the same country and tags
For each prompt you can set:
* **Topic**: the category this prompt belongs to (select an existing topic or create a new one)
* **Country**: the geographic context for the prompt
* **Tags**: labels for filtering and analysis
* **Keywords**: optional search terms associated with the prompt
## File Import
Upload a CSV or Excel file to add prompts in bulk.
1. Click **+ Add Prompts** → **File Import**
2. Upload your file or drag and drop
3. Map columns to the required fields (prompt text, country)
4. Optionally map topic, tags, and keywords
5. Review the parsed prompts
6. Save to your project
File import is useful when migrating prompts from spreadsheets, or when multiple team members contribute questions in a shared document.
## Suggested Prompts
Let AI generate prompt ideas based on a topic you describe. This is useful for discovering questions you hadn't considered or expanding into new topic areas.
1. Click **Suggest Prompts**
2. Select a **Topic** to assign generated prompts to (choose an existing topic or create a new one)
3. Add an optional **description** and **target audience** for more context
4. Select a **country** and **language**
5. Click **Generate**
Suggestions appear with a **Suggestion** badge. You can **accept** or **decline** each one individually or in bulk. Accepted prompts become active and are included in future data collection runs.
See [Suggested Prompts](/docs/suggested-prompts) for the full guide on reviewing and managing suggestions.
## Prompt Limits
Each project has a maximum number of active prompts, set by your team admin. You can check your remaining capacity before adding large batches. If you're approaching the limit, consider deactivating low-value prompts or speaking to your team admin about increasing the limit.
## Tips
* **Start with Suggested Prompts** if you're unsure what to monitor: describe your business and let AI generate ideas
* **Use Manual Entry** for specific questions you hear from customers or prospects
* **Use File Import** when you have an existing list of questions to monitor
* Add the **same prompt with different countries** to track regional differences, or use [Copy to Country](/docs/copying-prompts) after adding
Each project has a prompt limit set by your team admin. Check your remaining capacity before adding large batches.
# API Keys
Source: https://docs.surfacd.com/docs/api-keys
Create and manage API keys for your team's scripts, curl commands, or integrations.
API and MCP access is included on all plans. Browse the [API Reference](/api-reference) for the full list of endpoints.
API keys let trusted scripts, terminals, and integrations call the Surfacd API for a specific team. Create each key from the team that owns the data you want to access.
## Create a key
1. Open the team you want the key to access.
2. Go to **Team Settings** > **API Keys**.
3. Enter a name for the key, something that reminds you where you'll use it, like *Local script* or *Vercel integration*.
4. Click **Create Key**.
A dialog will appear showing the key once. **Copy it now** and store it somewhere safe. For your security, we can't show it to you again. If you lose a key, revoke it and create a new one.
## Use a key
Send the key as a `Bearer` token in the `Authorization` header, and call the API on `app.surfacd.com` or the team's own URL.
```bash theme={null}
curl 'https://app.surfacd.com/api/v1/team' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
A few things to know:
* **Keys belong to teams.** Create a separate key for each team or integration that needs API access.
* **The key selects the team.** Team-level endpoints do not need a team UUID. Project-scoped endpoints use project UUIDs from the same team.
* **Treat keys as team-level access.** Store them only in trusted systems and revoke keys that are no longer needed.
## Revoke a key
You can revoke any key from **Team Settings** > **API Keys**. Click **Revoke** next to the key. Calls using that key stop working immediately.
If a key may have been exposed (committed to a repo, pasted in a chat, etc.), revoke it straight away and create a new one.
## Security tips
* Treat keys like passwords. Don't share them, paste them in chats, or commit them to source control.
* Use a separate, named key per integration so you can revoke just that one if something goes wrong.
* Prefer environment variables or a secret manager over hardcoding keys.
* Rotate keys periodically: revoke old ones and create a fresh one.
# API Routing
Source: https://docs.surfacd.com/docs/api-routing
How Surfacd API URLs are organised, including team-scoped and project-scoped endpoints, and how to discover the public identifiers you need.
API and MCP access is included on all plans. Browse the [API Reference](/api-reference) for the full list of endpoints.
The Surfacd API uses two URL families. Both authenticate with a team API key as a `Bearer` token; they only differ in how the resource is addressed.
## Two URL families
* **Team-scoped:** `https://app.surfacd.com/api/v1/team/...`. Use these when the operation is about the team: reading settings (`GET /api/v1/team`), team usage (`/usage`), and members (`/members`, `/members/{email}`).
* **Project-scoped:** `https://app.surfacd.com/api/v1/projects/{project}/...`. Use these for anything that targets a single project: project CRUD (read, update, delete, archive, share), prompts (`/prompts`, `/prompts/{prompt}`), and reporting (`/brand-rankings`, `/mentions`, `/visibility-over-time`, `/matrix-analysis`, `/sources-data/...`).
Project collection endpoints, such as `GET /api/v1/projects`, list the projects for your API key's team.
## Discovering identifiers
To find project UUIDs for the key's team, call the project collection:
```bash theme={null}
curl 'https://app.surfacd.com/api/v1/projects' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
Each project in the response includes a `uuid` you can use as `{project}` on project-scoped endpoints.
Reporting filters use public identifiers only. Numeric database IDs are not part of the API contract.
* `brands`: brand UUIDs from `GET /api/v1/projects/{project}/brands`
* `tags`: tag UUIDs or names (case-insensitive) from `GET /api/v1/projects/{project}/tags` (each tag may include a `color` palette name: `gray`, `blue`, `cyan`, `purple`, `pink`, `red`, `orange`, `yellow`, `green`, `teal`; null displays as grey)
* `topics`: topic UUIDs or names (case-insensitive) from `GET /api/v1/projects/{project}/topics`, or `no_topic`
* `services`: platform provider strings from `GET /api/v1/platforms`
* `countries`: country codes from `GET /api/v1/countries`
* `categories`: enum values from `GET /api/v1/domain-categories`
* `prompt`: a prompt UUID from `GET /api/v1/projects/{project}/prompts`
Project service selection also uses `services`, but it accepts either platform provider strings, for example `chatgpt` or `perplexity`, or platform UUIDs. `GET /api/v1/platforms` returns both.
# Brand Mentions
Source: https://docs.surfacd.com/docs/brand-mentions
Scan every captured AI answer and focus on where your brand appears.
## All Answers vs Mentioned Only
Mentions defaults to **All Answers** — every AI response Surfacd captured for your prompts, including answers that omit your brand. Use this to spot gaps and turn missing mentions into an action list.
Switch to **Mentioned Only** when you want to focus on answers that name the selected brand.
## The Mentions Table
| Column | Shows |
| - | - |
| Platform | The AI service that produced the answer, with the prompt country flag on the icon (hover shows e.g. “ChatGPT in Argentina”) |
| Answer | Prompt (muted) above the mention snippet or response excerpt, with brand highlighting |
| Rank | Your brand's position in the answer (— if omitted) |
| Sentiment | Sentiment towards the selected brand (— if omitted) |
| Brands | Brands that appear in the answer |
| Date | When the answer was collected (Today / Yesterday, otherwise short date) |
Click any row to open the full AI response.
## Answer Detail
Click any row to open the full answer. The panel shows the prompt, the complete response, the brands mentioned and the sources cited.
For platforms that search the web before answering, the panel also lists the **Search Queries** the AI ran, in the order it issued them. These are the searches whose top results the AI read, so content that ranks for them is what shapes the answer. Platforms that answer from their own knowledge show no search queries.
## Filters
* **Brand** - Selected brand for Rank and Mentioned Only
* **Date Range** - Time period
* **Topics** - Filter by prompt topic categories
* **Tags** - Filter by custom prompt labels
* **Services** - Focus on specific platforms
* **Geos** - Filter by country
* **Sentiment / Rank** - Narrow to answers where the selected brand matches
## Sentiment
Sentiment is measured *towards the brand*. For example, if a brand is shown in a positive light within a negative topic, it will return "positive" rather than negative.
| Type | Meaning |
| - | - |
| Positive | Favourable ("excellent choice", "highly recommended") |
| Neutral | Factual, no strong tone |
| Negative | Criticism or concern mentioned |
For a deeper view of sentiment across themes, narratives, and competitors, see [Reputation](/docs/reputation).
## Rank
Rank 1 = mentioned first (highest prominence). First-mentioned brands get more attention. In All Answers, rows where the brand is missing show — instead of a rank.
## What to Look For
* **Missing mentions:** Answers that omit your brand but name competitors
* **How you're described:** What adjectives and features are highlighted?
* **Accuracy:** Any incorrect or outdated information?
* **Patterns:** Recurring strengths or criticisms?
* **Comparison:** How do competitors' appearances differ?
## Export
Click **Export** for an Excel download of the current view (All Answers or Mentioned Only) based on your filters. Columns: Platform, Date, Prompt, Mention, Country, Rank, and Brands.
## Tips
* Start in All Answers to find gaps, then switch to Mentioned Only for qualitative review
* Review weekly — read actual answers, not just counts
* Focus on your brand first, then compare to competitors
* Negative mentions may signal issues to address
* Look for patterns across multiple answers, not individual ones
# Brand Rankings
Source: https://docs.surfacd.com/docs/brand-rankings
Compare your brand's visibility against competitors across AI platforms.
## The Rankings Table
| Column | Shows |
| - | - |
| Rank | Position based on visibility (#1 = best) |
| Change | Movement since previous period (↑ improved, ↓ declined) |
| Brand | Company name and logo |
| Visibility Score | % of responses mentioning this brand |
| Sentiment Score | 0–100 Net Sentiment Index across this brand's mentions, with trend |
| Mentions | Total mention count with trend |
Click the **star icon** on any brand row to mark it as a [competitor](/docs/competitors) for focused tracking.
## Competitor Visibility Chart
The expandable chart at the top of the Rankings page visualises how your brand's visibility compares to competitors over time.
* **Up to 10 brands** can be displayed simultaneously
* Your **primary brand** is highlighted with a thicker line
* Each brand gets a distinct colour from your team's palette
* **Hover** over any point for exact values and dates
* **Export** the chart data to Excel for stakeholder presentations
By default, the chart shows your primary brand plus your top competitors. If no competitors are marked, the top-ranked brands are selected automatically. You can manually add or remove brands from the chart.
## Filters
* **Brand**: select specific brands to compare
* **Date Range**: time period for calculations
* **Topics**: filter by prompt topic categories
* **Tags**: filter by custom prompt labels
* **Services**: focus on specific AI platforms
* **Countries**: country-specific rankings
* **Competitors Only**: toggle to show only your primary brand and marked competitors
## Key Insights
**Gaps matter as much as position:**
* \#2 at 74% vs #1 at 75% = close race
* \#2 at 50% vs #1 at 90% = significant gap to close
**Use filters strategically:**
* By tag: "How do we rank for 'Enterprise CRM'?"
* By service: "How do we rank on ChatGPT vs Gemini?"
* By country: "How do we rank in US vs UK?"
## Export
Click **Export** to download rankings data in Excel format. Includes all visible data based on current filters. Use the **Competitors Only** toggle to generate focused competitive reports.
## Tips
* Check weekly at minimum
* Focus on trends over time, not single data points
* When ranking changes, investigate: check competitor mentions, research their recent activity
* Use the competitor visibility chart for stakeholder presentations; it tells a clear visual story
* Improving rankings takes sustained effort over months. There are no quick fixes
# Competitors
Source: https://docs.surfacd.com/docs/competitors
Curate which brands you actively track to focus your analysis on the competitors that matter most.
When Surfacd collects data from AI platforms, it discovers every brand mentioned in the responses, often dozens across your prompt library. Not all of them are relevant to your business. The competitors feature lets you curate this list, marking the brands you actually compete with so your reports focus on what matters.
## How Brand Tracking Works
Surfacd automatically identifies and tracks **every brand** mentioned in AI responses to your prompts. This means your data captures the full competitive landscape without any manual setup. However, for meaningful analysis you need to separate the signal from the noise.
| Brand Type | Meaning |
| - | - |
| **Primary** | Your brand: one per project, always highlighted in reports |
| **Competitor** | Brands you've chosen to actively track and compare against |
| **Other** | All remaining brands discovered in AI responses |
## Marking Competitors
On the **Rankings** page, click the **star icon** on any brand row to mark it as a competitor.
* Your **primary brand** is highlighted with your team's brand colour and is always included in reports
* **Competitors** are shown with a **gold star**
* **Other brands** show an empty star; they're still tracked but not highlighted
## Where Competitors Apply
### Rankings
Toggle **Only show competitors** to filter the rankings table and visibility chart to your primary brand plus competitors only. This strips away the noise and gives you a clean competitive view.
### Analyse (Matrix)
When the competitors toggle is enabled and Brand is a dimension, the matrix focuses on your primary brand plus your competitors, making cross-dimensional analysis clearer.
### Charts
The competitor visibility chart auto-selects your primary brand plus up to 4 competitors. If you haven't marked any competitors, the top 4 ranked brands are selected instead.
### Exports
Use the **Competitors Only** toggle before exporting to generate focused competitive reports that only include the brands you care about.
## Tips
Mark 5–10 direct competitors. You can always add more as your understanding of the landscape evolves.
New brands appear in AI responses over time. Check your rankings monthly for emerging competitors worth tracking.
Export with competitors only enabled to create clean competitive reports for stakeholders, with no clutter from irrelevant brands.
# Copying Prompts to Other Countries
Source: https://docs.surfacd.com/docs/copying-prompts
Duplicate your prompts across multiple countries to track regional differences in AI visibility.
AI responses vary significantly by geography. The same question asked in the UK and the US can produce different brand recommendations, different sources, and different positioning. Copying prompts across countries lets you track these regional differences without manually recreating each prompt.
## How to Copy Prompts
1. Navigate to your project's **Prompts** tab
2. Select the prompts you want to copy using the checkboxes
3. Click **Copy to Country** in the bulk actions toolbar
4. Select one or more **target countries**
5. Confirm the action
Surfacd creates a copy of each selected prompt for each target country. Topics, tags, and keywords from the original prompts are preserved.
## What Gets Copied
| Copied | Not Copied |
| - | - |
| Prompt text | Historical response data |
| Topic | Visibility scores |
| Tags | N/A |
| Keywords | N/A |
Each copied prompt is a new, independent prompt that will be included in future data collection runs for its assigned country.
## Duplicate Handling
Surfacd automatically detects duplicates. If a prompt with the same text already exists for a target country, it's skipped rather than duplicated. After copying, you'll see a summary showing how many prompts were created versus skipped.
## Credit Impact
Copied prompts are new active prompts, so they affect your credit usage:
* **Scheduled projects** (Daily/Weekly): Your credit reservation is recalculated to include the new prompts
* **Pitch projects**: Copied prompts count toward the pitch's prompt limit but use no credits
Surfacd checks your available credits before copying and will let you know if you don't have enough.
## Use Cases
Monitor the same questions across all your target markets to compare regional visibility.
Copy your proven prompts to a new market before launching to understand the competitive landscape.
Track how campaigns affect visibility differently across regions.
Compare how competitors perform in different countries with identical questions.
## Tips
* Start with your best-performing prompts: copy the ones that give you the most useful insights
* Use the **Matrix Analysis** with the **Country** dimension to compare results across regions (see [Matrix Analysis](/docs/matrix-analysis))
* You can select up to 100 prompts to copy at once
* After copying, check the [Usage](/docs/usage-billing) page to see the credit impact
# Custom Domains
Source: https://docs.surfacd.com/docs/custom-domains
Connect your own branded domain to access Surfacd under your company's URL.
Use your own domain (e.g., `insights.yourcompany.com`) to access Surfacd with your branding.
## Overview
Custom domains allow your team to access Surfacd at a URL you control, such as:
* `insights.yourcompany.com`
* `ai-analytics.yourcompany.com`
This provides a seamless, branded experience for your team and stakeholders.
Contact support to enable this feature.
## How It Works
1. You choose a subdomain on your domain (e.g., `insights.yourcompany.com`)
2. You add a DNS record pointing to our service
3. We automatically provision an SSL certificate
4. Your team accesses Surfacd at your custom URL
Your existing team subdomain (e.g., `yourteam.surfacd.com`) continues to work alongside your custom domain.
## Setup Instructions
### Step 1: Choose Your Domain
Pick a subdomain you'd like to use. Common choices:
* `insights.yourcompany.com`
* `surfacd.yourcompany.com`
* `ai.yourcompany.com`
* `visibility.yourcompany.com`
You must use a subdomain (e.g., `insights.yourcompany.com`), not your root domain (`yourcompany.com`).
### Step 2: Request Custom Domain
Contact Surfacd support with your desired domain. They will register it in our system.
### Step 3: Add DNS Record
Add a **CNAME** record in your DNS provider:
| Type | Name | Target |
| - | - | - |
| CNAME | `insights` (or your chosen subdomain) | `custom.surfacd.com` |
1. Go to your domain's DNS settings
2. Click **Add Record**
3. Select **CNAME** as the type
4. Enter your subdomain name (e.g., `insights`)
5. Enter `custom.surfacd.com` as the target
6. **Disable the proxy** (grey cloud) - this is important
7. Click **Save**
1. Go to your hosted zone
2. Click **Create Record**
3. Enter your subdomain name
4. Select **CNAME** as the record type
5. Enter `custom.surfacd.com` as the target
6. Click **Create records**
Look for DNS or Domain settings in your provider's dashboard. Add a CNAME record pointing your subdomain to `custom.surfacd.com`.
### Step 4: Wait for Verification
After adding the DNS record:
1. DNS propagation takes **5 minutes to 48 hours** (usually under 1 hour)
2. SSL certificate is automatically provisioned
3. Your administrator will confirm when the domain is active
### Step 5: Access Your Custom Domain
Once active, visit your custom domain (e.g., `https://insights.yourcompany.com`).
You'll need to log in again on your custom domain. Sessions are separate between domains for security.
## Troubleshooting
### Domain Shows "Pending"
The DNS record hasn't been detected yet. Check that:
* The CNAME record is correctly configured
* You're using a subdomain, not the root domain
* DNS has had time to propagate (wait up to 1 hour)
* If using Cloudflare, the proxy is **disabled** (grey cloud)
### SSL Certificate Error
SSL certificates are provisioned automatically. If you see certificate errors:
* Wait 15-30 minutes for the certificate to be issued
* Ensure no CAA records are blocking certificate issuance
* Contact your administrator if issues persist
### Can't Log In
If you're redirected back to the login page:
* Clear your browser cookies for the domain
* Ensure you're a member of the team that owns the custom domain
* Try using an incognito/private browser window
## FAQ
No, custom domains must be subdomains (e.g., `insights.yourcompany.com`). Root domains (`yourcompany.com`) are not supported due to DNS limitations with CNAME records.
No, your existing team subdomain (e.g., `yourteam.surfacd.com`) continues to work. You can use both.
No, both domains access the same team and data. Only the login session is separate for security.
Yes, contact your administrator to update your custom domain. Note that any bookmarks or shared links to the old domain will stop working.
No, SSL certificates are automatically renewed before expiration.
## Need Help?
Contact your Surfacd administrator or reach out to our support team at [support@surfacd.com](mailto:support@surfacd.com).
# Customising Your Brand
Source: https://docs.surfacd.com/docs/customising-your-brand
Make Surfacd your own with custom colours, logos, team branding, and your own domain.
Surfacd is designed to feel like an extension of your brand. When you share dashboards with stakeholders or present reports to leadership, a branded experience builds trust.
## Team Name
Your team name appears throughout the application: in navigation, headers, and on login screens. Choose a name that represents your organisation or department.
To update: **Settings** → **General** → **Team Name**
## Colour Palette
Choose a primary colour palette that matches your brand identity. This colour is applied to buttons, links, charts, and accents across the entire platform.
**Available palettes:**
Blue, Indigo, Purple, Red, Orange, Yellow, Green, Teal, and Slate.
To update: **Settings** → **General** → **Primary Colour**
Your selected palette applies to all charts, graphs, and data visualisations, ensuring consistent branding across every report and export.
## Logo
Upload your company logo to replace the default branding in the header and on login screens. When stakeholders access your dashboards or shared reports, they'll see your logo, not ours.
* **Supported formats:** PNG, SVG, JPEG
* **Maximum file size:** 512KB
* **Recommendation:** Use a horizontal/landscape logo for best results in the header
To update: **Settings** → **General** → **Logo**
## Icon
Upload a small icon (typically your favicon or logo mark) for the browser tab and navigation. This provides a polished, branded experience even at small sizes.
* **Supported formats:** PNG, SVG, JPEG, ICO
* **Maximum file size:** 512KB
* **Recommendation:** Use a square image (e.g., 512×512px) for consistent display
To update: **Settings** → **General** → **Icon**
## Custom Domain
Take branding a step further by accessing Surfacd on your own domain. Instead of using a Surfacd URL, your team can access the platform at an address you control:
* `insights.yourcompany.com`
* `ai-analytics.yourcompany.com`
* `visibility.yourcompany.com`
This is particularly valuable when:
* **Sharing with stakeholders** who expect tools to live under your company's domain
* **Embedding in your workflow** alongside other internal tools
* **Maintaining brand consistency** across your entire toolset
### Setting Up a Custom Domain
1. **Choose a subdomain** on your company's domain (e.g., `insights.yourcompany.com`)
2. **Contact Surfacd support** to register the domain
3. **Add a CNAME record** in your DNS settings pointing your subdomain to Surfacd
4. **Wait for verification** (SSL certificates are provisioned automatically)
5. **Access your platform** at your new branded URL
Your existing Surfacd URL continues to work alongside your custom domain, automatically redirecting team members to your branded URL.
For detailed setup instructions, DNS configuration for specific providers, and troubleshooting, see [Custom Domains](/docs/custom-domains).
Custom domains must use a subdomain (e.g., `insights.yourcompany.com`). Root domains are not supported.
## Default Country
Set a default country for your team. This pre-selects the country when team members create new projects, saving time and ensuring consistency across your organisation.
To update: **Settings** → **General** → **Default Country**
## Bringing It All Together
When fully configured, your Surfacd experience includes:
* Your **logo** in the header and login screens
* Your **icon** in browser tabs
* Your **colour palette** across all buttons, charts, and accents
* Your **team name** in navigation
* Your **custom domain** in the browser address bar
* Your **default country** pre-selected for new projects
The result is a platform that looks and feels like it was built for your organisation, ready for client presentations, stakeholder dashboards, and internal reporting.
## Tips
If you regularly share your screen during meetings or presentations, branded colours and your logo make a significant impression. Take two minutes to set these up before your next review.
When sharing dashboards with external stakeholders, a custom domain and branded UI builds confidence in the data. It feels like your tool, not a third-party service.
# Dashboard
Source: https://docs.surfacd.com/docs/dashboard
The Dashboard provides an at-a-glance overview of your brand's AI visibility with key metrics and trends.
## Header
* **Last Collection Date**: when data was last gathered
* **Request New Run**: trigger on-demand data collection
* **Share**: manage sharing settings for this project
* **Settings** (gear icon): access project settings
## Filter Controls
| Filter | Purpose |
| - | - |
| Brand | Select which brand to view (defaults to your primary brand) |
| Date Range | Time period for data |
| Topics | Filter by prompt topic categories |
| Tags | Filter by custom prompt labels |
| Services | Focus on specific AI platforms |
| Countries | Filter by geography |
Filters apply across all dashboard cards and persist as you navigate between report tabs.
### Saved Views
Save the filters you use most and reopen them in one click from any report page.
1. Set up your filters
2. Open the chevron next to the page name in the breadcrumb
3. Choose **Save current view**, check the filters listed in the dialog, and give the view a name
Saved views are listed in the same menu. Views for the current page appear first, and you can search across every page's views, rename them, or delete them.
Dates can be saved three ways: leave them out so the view uses whatever range you have active, pin the exact dates, or choose a rolling range such as **Last 28 days** or **Previous month** that resolves to fresh dates each time you apply it.
## Visibility Chart
Plots one line per brand shown in the Industry Ranking card, so you can compare your trend against your competitors'. Hovering or clicking a row in that card highlights the matching line.
Use the **Visibility / Sentiment** toggle to switch which metric is charted, and the **D / W / M** toggle to view daily, weekly or monthly buckets. The period toggles appear once the project has enough collected history.
### Visibility
How often your brand appears in AI responses, as a percentage.
* **90–100%** = Excellent: your brand dominates the conversation
* **70–89%** = Strong: consistently recommended
* **50–69%** = Moderate: appearing but room to grow
* **Below 50%** = Needs attention: competitors may be more visible
### Sentiment
How favourably your brand is described when it does appear, as a 0–100 score. See [Rankings](/docs/brand-rankings) for how the score is calculated.
A period with no mentions has no sentiment to report, so the line bridges the gap rather than dropping to zero. A brand can hold steady visibility while its sentiment slides, which is why the two are worth reading side by side.
Look for trends in either metric: upward (improving), downward (investigate), stable (consistent).
## Industry Ranking
Your position versus competitors based on visibility score. Shows the top brands in your space with:
* **Rank** and **rank change** (green ↑ improved, red ↓ declined)
* **Visibility score** with trend indicator
* **Sentiment score** (0–100) with colour band and trend
* **Brand logo** and name
Click **View all** for the full [Rankings](/docs/brand-rankings) report.
## Brand Position Distribution
Shows where your brand appears when mentioned in AI responses:
* **1st position**: mentioned first (highest prominence)
* **2nd position**: mentioned second
* **3rd position**: mentioned third
* **4th and beyond**: mentioned further down
First-mentioned brands typically receive the most attention. Track this distribution over time to see if your brand is moving higher in response order.
## Top Sources
The websites most frequently cited by AI platforms when responding to your prompts. Each source shows:
* **Domain name** with favicon
* **Citation count** and trend
* **Rank change** since previous period
This reveals which publications most influence AI responses in your space. See [Source Analysis](/docs/source-analysis) for deeper analysis.
## Source Categories
A visual breakdown of citations by type of website:
| Category | Examples |
| - | - |
| UGC | Reddit, LinkedIn, Quora |
| Editorial | News sites, independent blogs |
| Corporate | Company websites |
| Reference | Wikipedia |
| Academic | University sites, research papers |
| Analyst & Research | Forrester, G2, Gartner |
| Institutional | Government websites |
Toggle between chart and table view to explore the distribution. This helps you understand what types of content AI platforms value in your industry.
## Recent Mentions
The latest instances where your brand was mentioned in AI responses. Each mention shows:
* **Prompt** that triggered the mention
* **Mention snippet** with your brand name highlighted
* **Rank position** (with trophy icons for top 3)
* **AI service** that generated the response
* **Country** context
* **Other brands** mentioned in the same response
Click any mention to open the full detail view. Click **View all** for the complete [Mentions](/docs/brand-mentions) report.
## Navigation
| Tab | Purpose |
| - | - |
| Rankings | Detailed competitor comparison with visibility charts |
| Mentions | All brand mentions with context and sentiment |
| Prompts | Manage and analyse tracked questions |
| Sources | Analyse cited websites and their influence |
| Analyse | Cross-dimensional matrix analysis |
## Quick Review Cadence
* **Daily (5 min):** Check latest run completed, scan for major ranking changes
* **Weekly (15 min):** Compare to previous week, review ranking movements, read recent mentions
* **Monthly (1 hr):** Export data, document trends, plan actions based on insights
# Exporting Data
Source: https://docs.surfacd.com/docs/exporting-data
Download your AI visibility data as Excel files for reporting and further analysis.
Every report page in Surfacd supports exporting to Excel (.xlsx). Exports respect your current filters, so you get exactly the data you're viewing.
You can view the dedicated export section for each report to see the details:
* [Brand Rankings](brand-rankings#export)
* [Brand Mentions](brand-mentions#export)
* [Matrix Analysis](matrix-analysis#export)
* [Source Analysis](source-analysis#export)
* [Themes & Narratives](themes-narratives#export)
## Filters Apply to Exports
All exports use your currently active filters:
* **Date Range** (required for most exports)
* **Brand** (required for mentions and prompts exports)
* **Topics** - Only include prompts in selected topic categories
* **Tags** - Only include prompts with matching labels
* **Services** - Only include selected AI platforms
* **Countries** - Only include selected regions
* **Search term** - Applied where active
## Access
* Exports require a team account (not available via shared links)
* Your team role must include download permissions
* Maximum 10,000 records per export
## Tips
* Set your filters before exporting to get focused data sets
* Sources "By Domain" is useful for quick PR target lists
* Schedule regular exports (weekly/monthly) to track progress over time
# Quickstart
Source: https://docs.surfacd.com/docs/getting-started
This guide walks you through setting up your first Surfacd project and collecting your first data.
Set up your first Surfacd project in 6 steps.
## 1. Create a Project
1. From Surfacd, click **+ Create Project**
2. Enter a name (e.g., "HubSpot - UK")
3. Select your **Country** (this sets the default geographic context for prompts)
4. Set **Check Frequency** to Daily or Weekly
## 2. Add Your Brand
During project creation, you'll be asked to set up your primary brand:
* Enter your **Brand Name**
* Add your **Brand Domain** (e.g., `hubspot.com`)
* Include **Aliases** for name variations (e.g., "Hub Spot", "HubSpot CRM")
## 3. Select AI Services
Choose which AI platforms to monitor:
* ChatGPT
* Google Gemini
* Perplexity
* Microsoft Copilot
* Grok
* Google AI Mode
* Google AI Overviews
Monitor all for a complete picture. See [Supported Platforms](/docs/supported-platforms) for details on each service.
## 4. Curate Topics
After creating your project, Surfacd analyses your brand and generates suggested **topics**: categories that will structure your prompt library (e.g., "Enterprise CRM", "Email Marketing", "Sales Automation").
* **Edit** topic names and descriptions to match your priorities
* **Add** new topics or **remove** ones that aren't relevant
* Set a **target audience** to tailor prompt generation
* Choose how many **prompts** to generate across your topics
See [Topics & Tags](/docs/tags-organisation) for more on how topics organise your prompts.
## 5. Review Prompts
Surfacd generates prompts for each of your topics automatically. On the Prompts page:
* **Review** the generated prompts: accept, edit, or remove any that aren't relevant
* **Add more** using manual entry, file import, or [Suggest Prompts](/docs/suggested-prompts)
**Good prompts are natural questions:**
* "What is the best CRM software for small businesses?"
* "Can you recommend email marketing tools?"
* "What are the pros and cons of Salesforce?"
Start with 20–50 prompts covering your key topics. See [Adding Prompts](/docs/adding-prompts) for a detailed guide.
## 6. Start Collecting Data
Your project is now set up and ready to go.
Click **Request New Run**. Results typically begin to arrive within a few minutes, runs may take up to a few hours to fully complete depending on the number of prompts you're tracking.
## What's Next
Once your first run completes:
* **Dashboard** shows your visibility score and ranking
* **Rankings** compares you against competitors
* **Mentions** defaults to every captured AI answer, with a switch to Mentioned Only
* **Sources** reveals which websites AI cites
* **Analyse** lets you compare across services, countries, and topics
## Tips
Daily gives you the richest data for trend analysis
Copy prompts to multiple countries to track regional differences
Enable sharing in project settings to share dashboards with stakeholders
# How Credits Work
Source: https://docs.surfacd.com/docs/how-credits-work
Understand how Surfacd's credit system works, how costs are calculated, and how to manage your team's usage.
Credits are the currency that powers data collection in Surfacd. Every time your prompts are submitted to AI platforms and the responses are captured and analysed, credits are consumed. Understanding how credits work helps you get the most value from your allowance.
## The Basics
Your team has a **monthly credit allowance** set by your plan. Each data collection run consumes credits based on a simple formula:
**Credits per run = Active Prompts × the credit cost of your selected platforms**
Most platforms cost **1 credit** per prompt check, so a project with 50 prompts monitoring 4 standard platforms uses **200 credits per run**.
Some premium platforms cost more per check because their underlying data is significantly more expensive to collect. **Claude costs 30 credits** per prompt check. The credit estimate shown when you configure a project's platforms always reflects the real total, so there are no surprises.
## How Credits Are Used
Scheduled projects reserve credits from your allowance; pitch projects are free.
### Scheduled Projects (Daily, Weekly)
For projects that run automatically, credits are **reserved upfront** when you configure the project. This ensures your scheduled runs are always covered.
**Reserved credits = Credits per run × Frequency multiplier**
| Frequency | Multiplier | Example (50 prompts × 4 services) |
| - | - | - |
| Daily | 30 | 200 × 30 = **6,000 credits/month** |
| Weekly | 5 | 200 × 5 = **1,000 credits/month** |
Reserved credits are deducted from your available balance immediately, guaranteeing your automated monitoring runs without interruption.
### Pitch Projects
[Pitch projects](/docs/pitch-projects) use no credits at all, neither reserved nor per-run. They're bounded by their own limits (parallel pitches, prompts per pitch, platforms) instead.
If you've already collected data and then add new prompts or services, you're only charged for the new combinations that haven't been collected yet, not the entire run again.
## Available Credits
Your available credits are calculated as:
**Available = Monthly Allowance − Reserved (scheduled)**
Scheduled reservations draw from your monthly allowance. The [Usage](/docs/usage-billing) page in your team settings shows a real-time breakdown.
## What Affects Credit Usage
| Factor | Impact |
| - | - |
| **More prompts** | More credits per run |
| **More services** | More credits per run |
| **Premium platforms** | Higher credit cost per prompt check (e.g. Claude at 30 credits) |
| **Higher frequency** | More credits reserved per month |
| **More projects** | Each project has its own credit usage |
When a platform is made unavailable by Surfacd, it is removed from active project service counts and scheduled reservations are recalculated. If that platform later becomes available again, projects will resume monitoring it only when the restored reservation fits within the team's credit allowance.
## Managing Your Credits
### Reducing Costs
* **Deactivate low-value prompts**: inactive prompts use no credits and keep their history in your reports
* **Be selective with services**: if a platform isn't relevant to your audience, disable it
* **Choose a lower frequency**: Weekly reserves fewer credits than Daily
* **Archive projects** you're no longer actively monitoring, which releases reserved credits
### Monitoring Usage
* Check the **progress bar** in your sidebar for a quick overview
* Visit **Settings → Usage** for detailed breakdowns by project
* A warning appears when your projected usage approaches your allowance
### What Happens When Credits Run Out
* **Scheduled projects** continue to run as long as credits were reserved when the project was configured
* **On-demand runs** will be blocked if insufficient credits are available; you'll see a message explaining the shortfall
* No data is lost. Once credits are replenished, you can resume data collection
## Credit Validation
Surfacd checks credit availability before any action that would increase usage:
* **Creating a scheduled project**: validates the reservation fits within your allowance
* **Adding prompts to a scheduled project**: validates the increased reservation
* **Changing frequency**: validates the new reservation amount
* **Requesting a new run**: validates credits are available for the run cost
If there aren't enough credits, you'll see a clear message explaining how many are needed and how many are available.
## Tips
Start with a Weekly schedule for most projects, and step up to Daily only for active campaigns where you need the richest trend data.
Check your Usage page monthly. Identify expensive projects and deactivate prompts or disable services you're not using.
The credit indicator in your sidebar gives you an instant read on your team's usage without navigating away.
Team admins can set **Maximum Schedule Frequency** and **Prompt Limits** in team settings to prevent unexpected credit usage.
# Introduction
Source: https://docs.surfacd.com/docs/introduction
Understand your brand's AI search performance and identify the sources that influence it.
Your buyers aren't Googling anymore. They're asking ChatGPT, Gemini, and Perplexity for recommendations. These AI platforms don't show ten blue links. They give one answer.
**If your brand isn't in that answer, you're invisible.**
Traditional SEO tools can't help you here. They track keywords and rankings on Google, but AI search works differently. AI systems synthesise information from across the web to generate responses, and the platforms themselves give you nothing. No analytics. No performance data. No visibility into whether your brand makes the cut.
These systems are black boxes. Surfacd was built to open them.
## What Surfacd Does
Surfacd is AI Search Analytics. We query the major AI platforms with prompts relevant to your industry, capture the responses, and analyse how your brand performs. For the first time, you can understand, optimise, and grow your visibility in AI search.
You'll know:
* **Whether you're being recommended**, and how often
* **How you compare to competitors**, and who's winning the conversation
* **What sources influence the results**, so you can take action
## How It Works
Track how often your brand appears in AI conversations, and which competitors show up alongside you. We monitor ChatGPT, Gemini, Perplexity, Copilot, Grok, Google AI Mode, and Google AI Overviews.
Benchmark your visibility against competitors. See where you rank in recommendation lists, how AI describes your brand, and which external sources are shaping the responses.
Identify the sources that most influence AI answers. Prioritise your PR, content, and SEO efforts toward the publications and pages that will improve your visibility.
Track how your visibility changes over time. Measure the impact of your efforts and report outcomes with exportable data your stakeholders will trust.
## Real Results, Not API Approximations
Most tools that claim to track AI visibility take shortcuts. They query the underlying LLM APIs directly, which return different results than what your buyers actually see.
Surfacd works differently. We interact with the same interfaces your customers use: ChatGPT, Gemini, Perplexity, Copilot, Grok, Google AI Mode, and Google AI Overviews. This means the data you see in Surfacd matches reality. The citations, the recommendations, the way your brand is described, it's all captured exactly as users experience it.
This matters because the consumer-facing products often behave differently from their APIs. They use different system prompts, different retrieval sources, and different ranking logic. If you're optimising based on API results, you're optimising for the wrong thing.
## Why This Matters Now
AI search adoption is accelerating. The brands that understand this shift and act on it will capture attention while competitors remain invisible. Surfacd gives you the insight to move first.
# Joining a Team
Source: https://docs.surfacd.com/docs/joining-a-team
How to accept a team invitation and set up your account on Surfacd.
When someone invites you to their team, you'll receive an email with a link to join.
## Accepting Your Invitation
1. Check your email for an invitation from Surfacd
2. Click **Accept Invitation** in the email
3. You'll be directed to complete your account setup
Invitation links expire after 7 days. If your link has expired, ask your team admin to resend the invitation.
## New Users
If you don't have an account yet:
1. Click the invitation link
2. Create a password for your account
3. Click **Complete Setup**
You'll be logged in automatically and taken to your new team's dashboard.
## Existing Users
If you already have an account:
1. Click the invitation link
2. If you're already logged in, you'll join the team automatically
3. If you're logged out, you'll be prompted to sign in first
Once signed in, you'll be added to the team and can access shared projects.
## Team Roles
Your team admin assigns you a role that determines what you can do:
| Role | Capabilities |
| - | - |
| **Owner** | Full control: manage billing, team settings, and transfer ownership |
| **Admin** | Manage team settings, invite members, create and edit all projects |
| **Member** | Create, edit, share, and delete any team project |
| **Viewer** | View-only access to all team projects and reports |
Need a different role? Contact your team admin to update your permissions.
## Auto-Provisioning
If your team has auto-provisioning enabled for your email domain, you'll be automatically invited when you first sign in with Google or Microsoft. You'll see a pending invitation on the team selector page. Click **Accept** to join.
## Multiple Teams
You can be a member of multiple teams. Switch between teams using the team selector in the navigation sidebar.
## Troubleshooting
The link may have expired (after 7 days) or already been used. Ask your team admin to resend the invitation from **Settings → Members**.
Make sure you've accepted the invitation by clicking the link in your email. If issues persist, contact your team admin.
Return to the sign-in page and try again. OAuth links can expire if the browser tab was left open or the authorization code was already used.
Contact your team admin to send a new invitation to your preferred email address.
# Managing Projects
Source: https://docs.surfacd.com/docs/managing-projects
Create, configure, and manage your Surfacd projects to monitor brand visibility across AI platforms.
A project is the container for all your AI visibility monitoring: brands, prompts, services, and collected data.
## Creating a Project
Surfacd guides you through a three-step wizard to get your project up and running.
### Step 1: Project Details
1. Click **+ Create Project** from your dashboard
2. If your team has [Pitch Projects](/docs/pitch-projects) enabled, choose the **Project Type**: **Ongoing monitoring** (pre-selected) or a free 7-day **Pitch** snapshot
3. Enter a **Project Name** (e.g., "HubSpot - UK")
4. Select a **Country**, which sets the default geographic context for your prompts
5. For ongoing monitoring, set the **Check Frequency**: Daily or Weekly. (A pitch always runs daily for its 7-day window, so there's no schedule to pick.)
### Step 2: Your Brand
1. Enter your **Brand Name** (this becomes your primary brand)
2. Add your **Brand Domain** (e.g., `hubspot.com`)
3. Optionally add **Brand Aliases**: alternative names AI might use (e.g., "Hub Spot", "HubSpot CRM")
### Step 3: Select AI Services
Choose which AI platforms to monitor. See [Supported Platforms](/docs/supported-platforms) for full details on each service.
Monitor all available services for a complete picture of your AI visibility. Different platforms recommend different brands.
### After Creation: Topics & Prompts
Once you complete the creation wizard, Surfacd guides you through two additional setup pages:
1. **Topics Curation**: Surfacd analyses your brand and generates suggested topics (prompt categories). You can edit, add, or remove topics, set a target audience, and specify how many prompts to generate.
2. **Prompts**: Prompts are automatically generated for each topic. Review the suggestions and accept or decline them, then add more using any of the [standard methods](/docs/adding-prompts).
See [Topics & Tags](/docs/tags-organisation) for more on how topics organise your prompt library.
## Check Frequency
| Frequency | Best For | Credit Impact |
| - | - | - |
| Daily | Active campaigns, competitive markets | Highest (credits reserved monthly) |
| Weekly | Regular monitoring (most common) | Moderate (credits reserved monthly) |
See [How Credits Work](/docs/how-credits-work) for more on how frequency affects your credit usage.
## Project Status
Your project's status updates automatically based on its configuration and data collection progress.
| Status | Meaning |
| - | - |
| Incomplete | No prompts added yet; add prompts to get started |
| New | Prompts configured but no data collected yet |
| Collecting | A data collection run is in progress |
| Completed | Latest run finished successfully; data is ready to explore |
| Failed | Latest run encountered an issue; request a new run |
## Data Collection Runs
* Click **Request New Run** in the project header to trigger immediate data collection
* Results typically arrive within 15–60 minutes depending on the number of prompts and services
* Scheduled runs (Daily, Weekly) execute automatically
## Starring Projects
Click the **star icon** on any project card to mark it as a favourite. Starred projects can be filtered on your dashboard for quick access.
## Archiving Projects
When a project is no longer needed but you want to preserve its data:
1. Open the project **Settings**
2. Click **Archive Project**
3. The project moves to the **Archived** tab on your dashboard
Archived projects stop collecting data and release any reserved credits. You can **unarchive** a project at any time to restore it. It returns on its original schedule, and Surfacd re-reserves the credits that schedule needs. If you don't have enough credits available, the restore is blocked with an exact "need X, have Y" message. You can edit the archived project first (reduce prompts, platforms, or frequency) to make it fit, or free up credits elsewhere.
Archived projects are available from the **Archived** tab and are hidden from the main project switcher.
Deleting an archived project permanently removes all its data. Archive first, then only delete if you're certain the data is no longer needed.
## Project Settings
Access settings via the **gear icon** in the project header to update:
* **Project Name** and **Check Frequency**
* **AI Services**: add or remove platforms to monitor. Each project must keep at least one platform selected.
* **Brands**: manage your primary brand, aliases, and competitors
* **Sharing**: enable public view-only links (see [Sharing & Collaboration](/docs/sharing-collaboration))
## Filtering and Searching Projects
Your dashboard provides several ways to find projects:
| Filter | Options |
| - | - |
| Tab | All, Monitoring (scheduled), Pitch ([Custom plans](/docs/pitch-projects), contact support), Archived |
| Owner | All projects, My projects |
| Starred | Show only starred projects |
| Search | Search by project name |
## Tips
* **One project per focus area** keeps analysis clear and manageable
* **Naming convention:** `[Brand] - [Region]` or `[Brand] - [Campaign]` for easy identification
* **Review monthly:** Are your brands and prompts still relevant? Any new competitors to add?
* **Star your most important projects** so they're always a click away
# Managing Prompts
Source: https://docs.surfacd.com/docs/managing-prompts
Prompts are the questions you monitor across AI platforms. Learn how to manage, organise, and optimise them.
Prompts are the questions submitted to AI services like ChatGPT, Gemini, and Perplexity. Surfacd captures the responses and analyses how your brand (and competitors) are mentioned. The quality and breadth of your prompts directly determines the quality of your insights.
## The Prompts Table
Navigate to the **Prompts** tab within any project to see all your tracked prompts.
| Column | Shows |
| - | - |
| Topic / Prompt | Topic rows in grouped view, or question text in list view |
| Visibility | Your selected brand's score for the topic or prompt |
| Avg. Position | Your brand's average position when it is mentioned |
| Top Brands | Up to 5 most frequently mentioned brands in responses |
| Country | Geographic context (with flag) |
| Estimated Popularity | Relative search intent indicator derived from traditional search volume (see [Prompts Report](/reports/prompts-report#estimated-popularity) for details) |
| Tags | Categories you've assigned |
You can sort by any column. Sort by visibility to quickly find your strongest and weakest prompts, or by popularity to focus on high-demand questions.
## Grouped View
Toggle between **flat list** and **grouped by topic** modes using the view switcher above the table. In grouped mode, topic rows are collapsed by default and show topic-level visibility, average position, and top brands. Expand a topic to see the prompt rows beneath it. Prompts without a topic appear under an "Uncategorized" group.
## Adding Prompts
Surfacd offers three ways to build your prompt library. See [Adding Prompts](/docs/adding-prompts) for a detailed guide on each method:
* **Manual Entry**: type prompts directly, one at a time or in bulk
* **File Import**: upload prompts from a CSV or Excel file
* **Suggested Prompts**: describe a topic and let AI generate relevant prompts for you (see [Suggested Prompts](/docs/suggested-prompts))
## Writing Good Prompts
**Use natural questions that your buyers would actually ask:**
* "What's the best email marketing tool for small businesses?"
* "Can you recommend a CRM that integrates with Outlook?"
* "How does HubSpot compare to Salesforce for mid-sized companies?"
**Avoid bare keywords:**
* "email marketing tools" ✗
* "CRM software comparison" ✗
**Cover different stages of the buyer journey:**
| Stage | Example Prompts |
| - | - |
| Awareness | "What is a CDP?", "Why is my email open rate low?" |
| Research | "Best CRM for small business", "Top marketing automation tools" |
| Evaluation | "HubSpot vs Marketo", "Is Asana secure for enterprise?" |
| Purchase | "How much does Slack cost?", "Zoom enterprise plan pricing" |
| Retention | "How to export contacts from HubSpot", "Integrate Gmail with Notion" |
**Be specific but not too narrow:**
* Too broad: "What software should I use?"
* Too narrow: "What CRM for a 47-person B2B SaaS in Manchester?"
* Right: "What CRM is best for mid-sized B2B companies?"
## Prompt Status
Each prompt has a status that determines whether it's included in data collection.
| Status | Meaning |
| - | - |
| Active | Collects new data on every update and appears in your reports |
| Inactive | Stopped collecting, but its history stays in your reports |
| Suggestion | AI-generated prompt awaiting your review |
| Declined | A suggestion you've chosen not to use |
Only **Active** prompts count toward your project's prompt limit and credit calculations.
## Deactivating and Deleting Prompts
Prompt text can't be edited. Changing the question changes the answers AI gives, which would distort your trends. To replace a prompt, deactivate the old one and add the new one.
Prompts move through three stages: **Active → Inactive → Deleted**.
1. **Deactivate.** Select active prompts and click **Deactivate**. They stop collecting data and no longer use credits or count toward your prompt limit. Their history, topic and tags stay in place, so your reports still show how they performed. This is how you compare results before and after you replace a prompt.
2. **Reactivate or delete.** Deactivated prompts move to the **Inactive** tab. From there you can:
* **Reactivate** a prompt to start collecting again. This counts toward your prompt limit and credits like adding a new prompt.
* **Delete** a prompt to remove it and its history from all of your reports.
Active prompts can't be deleted directly. Deactivate them first.
If you deactivate every prompt in a project, data collection pauses. Your reports stay available, and collection resumes when you activate or add a prompt.
If you add a prompt that matches an inactive one (same text and country), Surfacd reactivates the existing prompt instead of creating a duplicate, so its history carries on.
## Bulk Actions
Select multiple prompts using the checkboxes, then choose an action from the toolbar:
| Action | What It Does |
| - | - |
| Add Tags | Add tags to selected prompts (keeps existing tags) |
| Replace All Tags | Replace all tags on selected prompts with new ones |
| Remove All Tags | Clear all tags from selected prompts |
| Change Topic | Assign or change the topic for selected prompts |
| Copy to Country | Duplicate prompts to additional countries (see [Copying Prompts](/docs/copying-prompts)) |
| Deactivate | Stop collecting data for active prompts while keeping their history in reports |
| Reactivate | Resume data collection for inactive prompts (Inactive tab) |
| Delete | Remove inactive prompts and their history from your reports (Inactive tab) |
## Inline Tag Editing
Hover over the tags column on any prompt row to reveal an edit icon. Click it to quickly add or change tags for that individual prompt without navigating away.
## Country Selection
Each prompt has a country that provides geographic context. AI responses can vary significantly by region: a prompt about "best banks" will return different results in the UK versus the US.
To monitor the same question across multiple countries, use [Copy to Country](/docs/copying-prompts) to duplicate prompts efficiently.
## Export
Click **Export** to download all prompts with their visibility data as an Excel file. Your current search and filter settings are applied to the export.
## Tips
* Start with **20–50 prompts** covering your key topics
* Use [Topics & Tags](/docs/tags-organisation) to organise prompts: topics for primary categories, tags for flexible filtering and matrix analysis
* Review regularly: deactivate prompts that are no longer relevant, and add new topics as your market evolves
* Sort by visibility to quickly find where you're winning and where you're not
* Use [Suggested Prompts](/docs/suggested-prompts) to discover questions you hadn't considered
Deleting a prompt removes it and its history from all of your reports. If you might still want to look back at a prompt's results, leave it inactive instead.
# Matrix Analysis
Source: https://docs.surfacd.com/docs/matrix-analysis
Cross-dimensional analysis to compare brands, services, countries, and topics side by side.
The **Analyse** tab provides a pivot table view that lets you compare any two dimensions against each other, with your choice of metric. This is the most powerful analysis tool in Surfacd.
## How It Works
Choose what goes on the **rows**, what goes on the **columns** and which **metric** to display in each cell.
### Dimensions
| Dimension | Shows |
| - | - |
| Brand | Your primary brand and competitors |
| Topic | Prompt categories (AI-generated or manually created) |
| Tag | Custom labels you've applied to prompts |
| Service | AI platforms (ChatGPT, Gemini, Perplexity, etc.) |
| Country | Geographic regions |
### Metrics
| Metric | Measures |
| - | - |
| Visibility Score | % of responses mentioning the brand |
| Industry Rank | Position relative to competitors (#1 = best) |
| Mention Count | Total number of mentions |
| Avg. Position | Average position when mentioned in a response |
## Reading the Matrix
Each cell shows the value for that row/column combination. For example:
Analyse **Visibility** comparing **Brands** by **Service**
| Brand | ChatGPT | Gemini | Copilot |
| - | - | - | - |
| Brand A | 82% | 76% | 70% |
| Brand B | 60% | 68% | 65% |
| Brand C | 45% | 51% | 58% |
| Brand D | 92% | 87% | 90% |
Shows each brand's visibility on each AI platform.
Analyse **Industry Rank** comparing **Topics** by **Country**
| Topic | United States | United Kingdom |
| - | - | - |
| Enterprise CRM | 1 | 2 |
| Email Marketing | 3 | 1 |
| Sales Automation | 2 | 5 |
| Data Analytics | 10 | 10 |
Shows how you rank by topic in each country.
To filter the report by **Topic**, **Tag**, **Service**, or **Country**, make sure you have:
* Enabled the relevant services when [setting up your project](getting-started)
* Selected the desired countries for prompts when [adding prompts](managing-prompts)
* Created topics and tags ([Topics & Tags](tags-organisation))
## Change Tracking
Toggle **Show Changes** to see how values shifted compared to the previous period. Changes display as:
* **Green** with ↑ = Improved
* **Red** with ↓ = Declined
* **Grey** = No change
The comparison period matches the length of your selected date range (e.g. if viewing the last 7 days, changes compare against the 7 days before that).
## Filters
The matrix respects all global filters:
* **Brand** - Select specific brand to compare against
* **Date Range** - Time period for calculations
* **Topics** - Filter by prompt topic categories
* **Tags** - Filter by your custom prompt labels
* **Services** - Focus on specific AI platforms
* **Geos** - Country-specific data
## Export
Click **Export** to download the matrix as an Excel file. The export includes all visible data based on your current dimension, metric, and filter selections.
## Tips
* Start with **Brand vs Service** to see where you're strongest and weakest across platforms
* Use **Topic vs Brand** to see which categories each competitor dominates
* Use **Tag vs Brand** for cross-cutting analysis by your custom labels
* **Country vs Service** reveals regional differences in AI responses
* Toggle changes on/off to spot trends vs. viewing absolute values
* Combine with the competitors filter for focused competitive analysis
# MCP for AI Assistants
Source: https://docs.surfacd.com/docs/mcp
Connect Claude, Cowork, ChatGPT, Codex and other AI assistants to Surfacd so they can read your data and run actions on your behalf.
API and MCP access is included on all plans. Browse the [API Reference](/api-reference) for the full list of
endpoints.
Surfacd ships an [MCP server](https://modelcontextprotocol.io/), a standard way for AI assistants to read your data and run actions on your behalf, with you approving the connection up front.
Use this endpoint in any remote MCP client:
```text theme={null}
https://app.surfacd.com/mcp
```
When your assistant connects, Surfacd opens a browser authorization flow at `app.surfacd.com/oauth/authorize`. Sign in, review the requested access, then click **Authorize**.
## What the assistant can do
Once connected, the assistant has tools for:
* **Reading:** list teams and projects, show a project's brand rankings, mentions, visibility-over-time, prompts, members, source breakdowns.
* **Explaining:** answer "why did visibility change?" — the assistant compares the selected period with the previous one, sees which services, countries, or topics drove the change (with noise flags), and drills into any segment before pulling example responses.
* **Reputation** (projects with Reputation enabled): overview KPIs, sentiment over time and per platform, themes and narratives, the AI responses behind them, and the sources cited in those responses.
* **Writing:** create projects and prompts, archive or share a project, update prompt status or tags, invite or revoke team members.
Report tools use the same filters as the product and API: platforms (`services`), countries, tags, and topics. Tags and topics accept a UUID **or** name (case-insensitive); topics also accept `no_topic` for uncategorised prompts.
The assistant acts as **you**. It can do exactly what you can do logged in, and the same per-team permissions apply. It cannot bypass project prompt limits or credit budgets.
## Connect your assistant
Claude calls remote MCP servers **custom connectors**. The same flow works for Claude, Cowork, and
Claude Desktop.
1. Open **Customize > Connectors**.
2. Click the **+** button next to **Connectors**.
3. Select **Add custom connector**.
4. Enter `Surfacd` as the name.
5. Enter `https://app.surfacd.com/mcp` as the URL.
6. Complete the Surfacd authorization flow.
If you're on a managed Claude Team or Enterprise workspace, an owner may need to add or approve the
connector from organization settings first.
Once connected, ask Claude something like *"list my Surfacd teams"* or *"summarise this week's brand
visibility for Acme"*.
ChatGPT lists custom MCP servers under **Apps & Connectors**.
1. Open **Settings > Apps & Connectors > Advanced Settings**.
2. Enable **Developer Mode**.
3. Under the developer mode options, click **Connect More** or **Create**.
4. Enter `Surfacd` as the name.
5. Enter `https://app.surfacd.com/mcp` as the server URL or HTTPS endpoint.
6. Authorize Surfacd when ChatGPT asks for permission.
7. Select Surfacd as a source in your chat.
When you want ChatGPT to use Surfacd, explicitly ask it to use tools, for example: *"use tools to list
my Surfacd teams"*. ChatGPT may ask you to approve write actions before they run.
Codex shares MCP settings across the Codex CLI, IDE extension, and desktop app.
In Codex Desktop:
1. Open **Settings** with `Command+,`.
2. Go to **MCP Servers**.
3. Select **Add MCP Server**.
4. Enter `Surfacd` as the name.
5. Select **Streamable HTTP**.
6. Enter `https://app.surfacd.com/mcp` as the URL.
7. Leave the other settings as their defaults.
8. Click **Save**.
If you prefer the CLI, add Surfacd as a streamable HTTP MCP server:
```bash theme={null}
codex mcp add surfacd --url https://app.surfacd.com/mcp
```
Then authenticate with Surfacd:
```bash theme={null}
codex mcp login surfacd
```
Inside a Codex session, run `/mcp` to confirm Surfacd is connected and its tools are listed.
For clients that use JSON configuration, add a server entry pointing at the Surfacd endpoint:
```json theme={null}
{
"mcpServers": {
"surfacd": {
"url": "https://app.surfacd.com/mcp"
}
}
}
```
The exact file location varies per client. Restart the client after editing its configuration; it should
detect that auth is required and walk you through the same browser authorization step as above.
## Disconnect
In Claude or Cowork, go to **Customize > Connectors**, open the Surfacd connector, then disconnect or remove it.
In ChatGPT, go to **Settings > Apps & Connectors**, open Surfacd, then disconnect it. Workspace admins can also disable the connector from workspace settings.
In Codex:
```bash theme={null}
codex mcp logout surfacd
codex mcp remove surfacd
```
In other clients, remove the `surfacd` entry from the config and restart.
To revoke access from the Surfacd side (for example, if a device is lost), visit your **profile page** and revoke the connected application. Calls using that grant stop working immediately.
## Safety notes
* The assistant only sees data from teams you belong to, with the same role you have in each.
* Destructive actions (delete a project, revoke a member) go through the same rules as the UI. A good rule of thumb: ask the assistant to confirm a destructive action before running it.
* Tool calls don't bypass project prompt limits or team credit budgets. If you're at your plan's cap, the assistant gets the same error you'd see in the UI.
* Revoke the connection if you stop using the assistant; reconnecting is one CLI command.
## Looking for the API instead?
If you want to call Surfacd directly from scripts or your own services, you want an [API key](/docs/api-keys) instead. MCP is specifically for AI assistants that speak the protocol.
# Pitch Projects
Source: https://docs.surfacd.com/docs/pitch-projects
Run a free 7-day AI visibility snapshot, then convert it to ongoing monitoring.
A pitch project is a time-boxed snapshot of AI visibility: it collects data daily for 7 days and then stops automatically. Pitch projects use no credits, which makes them a good fit for agency pitches, quick audits, or trying Surfacd on a new brand before committing to ongoing monitoring.
Pitch projects are available on Custom plans only. Contact support to enable them for your team.
## How the 7-Day Window Works
1. **Create the pitch.** In the project wizard, choose the **Pitch** project type (instead of the default, **Ongoing monitoring**), then set up your brand and platforms as usual.
2. **Add prompts.** The clock starts when your first prompts are collected, not when the project is created. A pitch with no prompts never starts its window.
3. **Daily collection for 7 days.** From the day of that first collection, the project collects once per day for seven calendar days.
4. **The window closes.** Collection stops automatically. All reports stay fully visible; the project just stops collecting new data.
You can follow the window from the projects list. Pitch projects carry a purple **Pitch** tag in the Type column, and the Last Update column shows where the window stands: "Awaiting first collection" before the clock starts, "Collecting: N days left" while it runs, and "Pitch complete" once it ends (hover the pill for the exact end date).
## Limits
Pitch projects don't use credits. Instead they have their own limits, set for your team:
| Limit | Meaning |
| - | - |
| Parallel pitches | How many pitches can be pending or running at once. Finished or archived pitches free up a slot. |
| Prompts per pitch | The maximum prompts a single pitch can track (the project's prompt limit is fixed at this value). |
| Platforms | Which AI platforms a pitch can monitor. |
Pitch projects don't count toward your plan's project limit, and your regular projects don't count toward your pitch allowance.
## What's Fixed on a Pitch
To keep pitches simple and free, a few settings are locked while a project is a pitch:
* **Schedule**: always daily for the 7-day window; it can't be changed.
* **Prompt limit**: fixed at your team's pitch prompt cap.
* **Platforms**: limited to your team's pitch platform list.
You can still edit prompts, brands, competitors, and tags at any time, including after the window ends (edits after the window don't trigger new collection).
## Converting to Ongoing Monitoring
Once the 7-day window has ended, you can convert the pitch into a regular ongoing project. Every prompt, brand, and all the data already collected is kept. The convert action appears in a few places:
* On the projects list: the convert icon next to the "Pitch complete" status (or the **Convert to ongoing** button in card view)
* On the project dashboard: a banner offering to convert the completed pitch
* In the project header: the convert icon next to the "Pitch complete" pill
Each opens the same dialog:
1. Pick **Daily** or **Weekly** monitoring (the choices offered depend on your plan)
2. Click **Convert**
Credits are reserved for the new schedule from that moment, and collection resumes on the schedule you picked.
Converting needs a free project slot and enough available credits. If credits are short, the dialog tells you exactly how many you need versus how many you have. Free up credits, adjust other projects, or upgrade, then try again.
Sharing works on pitch projects just like regular projects. A read-only share link to a finished pitch makes a useful leave-behind after a client presentation. See [Sharing & Collaboration](/docs/sharing-collaboration).
# Prompts Report
Source: https://docs.surfacd.com/docs/prompts-report
Analyse how each prompt performs across AI services with visibility scores and brand data.
The **Prompts** tab shows all your tracked prompts with performance data, helping you understand which questions drive visibility and which need attention.
## The Prompts Table
| Column | Shows |
| - | - |
| Topic / Prompt | Topic rows in grouped view, or question text in list view |
| Visibility | Your brand's visibility score for the topic or prompt |
| Avg. Position | Your brand's average position when it is mentioned |
| Top Brands | Up to 5 most-mentioned brands |
| Country | Geographic context with flag |
| Estimated Popularity | Relative search volume (5-dot scale) |
| Tags | Labels you've assigned |
## Grouped By Topic
By default, the Prompts table opens in **Group by Topic** view. Topic rows summarise the prompts in that topic, including overall visibility, average position, and the top brands for the topic. Expand a topic to see the prompt rows beneath it using the same columns.
## Visibility Score
Shows the percentage of AI responses that mention your selected brand for each prompt. Requires a **brand** and **date range** to be selected in the filter bar.
You can sort by visibility (click the column header) to find your strongest and weakest prompts.
## Estimated Popularity
A 5-dot indicator showing the relative search intent behind each prompt within your project.
### How it works
For each prompt, we derive a keyword that matches the underlying intent which represents a traditional web search query. We then use partner data vendors to retrieve the search volume for that keyword in the relevant country, providing a proxy for how much real-world demand exists behind the prompt.
This traditional search volume is mapped to a 5-point scale relative to the other prompts in your project:
| Dots | Level |
| - | - |
| 1 | Minimal |
| 2 | Low |
| 3 | Medium |
| 4 | High |
| 5 | Very High |
Hover for exact search volume. Popularity is relative to other prompts in your project.
:::note
Estimated Popularity is a **directional** data point: it helps you compare the relative importance of prompts within your project rather than providing an absolute measure. The "estimated" caveat reflects that search intent is used as a proxy for prompt popularity, which is imperfect but useful for prioritising which prompts matter most.
:::
## Filters
Beyond the global filter bar (Brand, Date Range, Topics, Tags, Services, Geos), the Prompts table adds:
* **Search** - Find prompts by keyword or text
* **Visibility Range** - Filter by minimum and/or maximum visibility percentage
## Bulk Actions
Select multiple prompts using the checkboxes, then choose an action:
| Action | What it does |
| - | - |
| Add Tags | Append tags to selected prompts (keeps existing tags) |
| Replace All Tags | Replace all tags on selected prompts with new ones |
| Remove All Tags | Clear all tags from selected prompts |
| Change Topic | Assign or change the topic for selected prompts |
| Deactivate | Stop collecting data for active prompts while keeping their history in reports |
| Reactivate | Resume data collection for inactive prompts (Inactive tab) |
| Delete | Remove inactive prompts and their history from your reports (Inactive tab) |
## Inline Tag Editing
Hover over the tags column on any row to reveal an edit icon. Click it to add or change tags for that individual prompt.
## Export
Click **Export** to download all prompts with their visibility data as an Excel file. Current search and filter settings are applied to the export.
## Tips
* Sort by visibility descending to find prompts where you're already strong
* Sort ascending to find prompts where competitors dominate and you need to improve
* Use the visibility range filter to quickly find prompts below a threshold (e.g., under 30%)
* Click a prompt to jump to the dashboard filtered to that specific question
* Organise prompts into topics and use tags for additional dimensions; both power the Matrix view
Active prompts must be deactivated before they can be deleted. Deleting a prompt removes it and its history from all of your reports. To keep a prompt's history visible, leave it inactive instead. See [Deactivating and Deleting Prompts](/docs/managing-prompts#deactivating-and-deleting-prompts).
# Report Downloads
Source: https://docs.surfacd.com/docs/report-downloads
Export project data pages as a PDF, download Rankings and Answers as Markdown, or print any page as a clean report.
Report pages can be taken with you as formatted documents, not just raw data tables. Where an Excel export gives you the underlying rows, a report download gives you the page itself: charts, tables and your active filters laid out as a shareable document.
## Export Project Data Pages as a PDF
Project reporting and prompt pages have an **Export as PDF** button in the header. Project Settings, Manage Tags and Manage Topics do not offer exports because they contain administration controls rather than report data. On smaller screens the export action appears as a download icon beside the **+** Add Prompts action. Click it to render and download the report:
* The button shows a loading state while the current page is rendered
* The download starts as soon as rendering finishes; keep the page open until it begins
* The PDF captures the page exactly as you have it filtered, so set the date range, models, tags and other filters first
What the PDF contains:
* A report header with your team logo, the project and page name, and a link back to the live page
* The date range and any active filters, written out in plain language
* The page's cards, charts and tables at full page width, with table headings repeated across pages
PDFs are returned directly and are not stored by Surfacd. Tables print the page of results you are currently viewing.
## Markdown Reports
Rankings and Answers can also be downloaded as Markdown for LLMs. Open the **Export** menu on the page (beside the search box above the rankings table, or next to the search on Answers) and pick a format:
* **Export as Markdown** — the report as plain Markdown. Paste it into an AI assistant to analyse or summarise your results.
* **Export as XLSX** — the raw rows behind the page (for example the rankings summary or the full answers table) rather than the formatted report.
The Markdown report includes the date range and active filters, the competitor visibility summary and top 25 rankings on Rankings, the latest 25 answers with mention snippets on Answers, and a link that reopens the report live with the same filters applied.
## Access
* PDF exports and report downloads require a team account with download permissions
* Markdown reports render fresh from your current filters and are not stored
## Printing Any Page
You can also use your browser's print command (`Cmd+P` on Mac, `Ctrl+P` on Windows) on any project page and choose **Save as PDF**. The result matches the exported PDF: navigation, filters and controls are left out, and the report header, filters and full-width cards take their place.
# Reputation
Source: https://docs.surfacd.com/docs/reputation
Understand what AI platforms say about your brand, not just whether you appear.
Visibility tells you whether you're in the answer. Reputation tells you what the answer means. You can win the mention and still lose the sale if AI describes you poorly.
Reputation analyses the responses Surfacd already collects and surfaces the stories AI platforms tell about your brand: what they say, whether it's helping or hurting, and how you compare to competitors. There's nothing extra to set up.
Reputation is included on every plan. It is in beta and free to use while it is.
## Enabling Reputation
Reputation is switched on per project:
1. Open your project and click **Reputation** in the sidebar
2. Click **Enable reputation for free**
You'll need edit access to the project. Analysis begins with your next data collection, so insights appear once that run completes.
Shared links only include Reputation if the project has it enabled. Visitors on a shared link can't enable it or export data.
## Key Concepts
| Term | Meaning |
| - | - |
| Narrative | A recurring story AI tells about your brand ("praised for fast support", "criticised for pricing") |
| Theme | A group of related narratives that share a topic, such as Pricing or Customer Support |
| Sentiment | Whether a mention is Positive, Neutral, or Negative towards the brand |
| Sentiment Score | A 0-100 score summarising sentiment across all mentions |
| % of Responses | The share of AI responses in which a narrative, theme, or brand appeared |
| Momentum | Whether a narrative is growing, stable, or fading versus the previous period |
| Surfaced By | Which AI platforms produced the mentions |
## The Sentiment Score
Every mention counts towards a single 0-100 score. Positive mentions push it up, negative mentions pull it down, and 50 means an even balance.
| Score | Reads as |
| - | - |
| 80-100 | Very Positive |
| 60-79 | Positive |
| 40-59 | Neutral |
| 20-39 | Negative |
| 0-19 | Very Negative |
## The Overview Tab
Your starting point each time you check in:
* **Sentiment** - how mentions split across positive, neutral, and negative, as a trend over time or a donut for the period
* **Sentiment Score** - your overall score, with the spread per AI model
* **Top Themes** - the most-mentioned themes this period, with a chart to plot them over time
* **Narratives** - the top narratives reinforcing the brand alongside those challenging it
## Filters
* **Brand** - all Reputation data is scoped to one brand at a time, defaulting to your primary brand
* **Date Range** - the period to analyse
* **Services** - focus on specific AI platforms
Every trend indicator compares your selected period against the previous period of the same length. If the previous period has no data, the indicator shows a dash.
## Going Deeper
* [Themes & Narratives](/docs/themes-narratives) - explore what AI is saying, story by story, with the evidence behind it
* [Reputation Insights](/docs/reputation-insights) - spot narratives on the move and compare how each platform tells your story
* [Competitor Reputation](/docs/reputation-competitors) - benchmark your sentiment and reach against competitors
# Competitor Reputation
Source: https://docs.surfacd.com/docs/reputation-competitors
Benchmark your sentiment and reach against competitors, theme by theme.
Every brand mentioned in your collected responses is analysed and scored the same way as yours, so you can benchmark reputation directly. The aim isn't just to win the mention, it's to win the sentiment too.
## Choosing Brands to Compare
The **Comparing** bar at the top holds your comparison set. The brand selected in the filter bar is always included; click **Add Brand** to add others, up to ten in total. Use the toggle to switch between the **Overview** and **Side-by-Side** layouts.
## Visibility vs. Sentiment
A scatter chart placing each brand by reach (% of responses mentioning it) and tone (sentiment score), with a tail showing how it moved since the previous period. The four quadrants tell you where each brand stands:
| Quadrant | Meaning |
| - | - |
| Strong reputation | Widely mentioned and well regarded |
| Visible, weaker sentiment | Mentioned often, but the tone needs work |
| Liked, less visible | Well regarded but not reaching enough answers |
| Out of the conversation | Rarely mentioned and not well regarded |
## Brand Overview
A league table ranking every compared brand by sentiment score, with % of responses alongside. Both columns carry trend indicators, so you can see who's gaining and who's slipping.
## Theme Comparison
The same theme matrix as [Reputation Insights](/docs/reputation-insights), but with brands as columns instead of platforms. It shows how each brand stands per theme, which is where competitive gaps get specific: you might lead overall but trail a rival on Pricing.
## Side-by-Side
The same data laid out as one profile per brand, useful for a direct one-to-one comparison or for screenshots in a competitive report.
## What to Look For
* **Your quadrant and direction** - the movement tail matters more than the position; heading towards "strong reputation" beats sitting still in it
* **Themes where a competitor leads** - read their narratives on that theme to understand the story AI tells about them and why it lands
* **Rivals in "liked, less visible"** - a well-regarded competitor gaining visibility is the one to watch
# Reputation Insights
Source: https://docs.surfacd.com/docs/reputation-insights
Spot narratives on the move and compare how each AI platform tells your story.
The Insights tab answers two questions: what changed this period, and does every AI platform tell the same story? Switch between the two views using the toggle at the top.
## Narrative Movers
Four boards track stories bubbling to the surface, comparing your selected period against the previous one:
| Board | Shows |
| - | - |
| Rising | The largest significant increases in % of responses |
| Cooling | The largest significant decreases in % of responses |
| Just appeared | Narratives first seen this period |
| Gone quiet | Narratives present last period, absent from this one |
Rising and cooling narratives show their previous and current share side by side, with the change in points. Click any narrative to open its detail page.
## Platform Comparison
The Theme Comparison matrix shows how each AI platform tells each theme. Themes are rows, platforms are columns, and each is measured against that platform's own responses, so a platform that talks less overall is still compared fairly.
* Toggle between **Sentiment score** and **% of responses** to compare tone or attention
* Switch on **Changes** to see how each cell moved since the previous period
* Hover over a cell for the full detail; an empty cell means that platform had no mentions in the theme this period
## What to Look For
* **A theme rising fast** - check whether it's positive momentum to build on or an emerging problem
* **One platform out of step** - if ChatGPT scores a theme far lower than the others, its sources or training data likely differ, and it may need its own plan
* **Gone quiet narratives** - a negative story disappearing is a win worth recording; a positive one fading may need reinforcing
# Sharing & Collaboration
Source: https://docs.surfacd.com/docs/sharing-collaboration
Share view-only access to your dashboards with stakeholders who don't have accounts.
![Share settings]()
## Enabling Sharing
1. Open your project and click the **Share** button in the header
2. Toggle **Enable Sharing** on
3. Copy the generated share link
4. Optionally set a **Password** for sensitive data
## What Shared Users Can Access
**Can do:**
* View all analytics (dashboard, rankings, mentions, sources, matrix)
* Use filters and date ranges
* Browse all report tabs
**Cannot do:**
* Edit settings, brands, or prompts
* Request data collection runs
* Export data
* Access other projects
## Managing Access
* **Revoke access:** Toggle sharing off; existing links stop working immediately
* **Generate a new link:** Click **Refresh Token** to create a fresh link and invalidate the old one
* **Set or change password:** Update in the share settings and communicate to stakeholders
* **Remove password:** Leave the password field blank to allow open access via the link
## Tips
Send links and passwords through different channels for added security.
Review sharing settings periodically and disable sharing when no longer needed. Refresh the token if you suspect the link has been shared more widely than intended.
For stakeholders who need to manage projects or export data, invite them as team members instead. See [Team Settings](/docs/team-settings) for role options.
# Source Analysis
Source: https://docs.surfacd.com/docs/source-analysis
See which websites AI services cite in their responses.
Understand what pages are being cited and influencing the results from AI. So that you can adjust outbound strategies to influence the AI outputs in the future.
## Views
* **By URL** - Individual pages cited
* **By Domain** - Aggregated by website (hubspot.com)
* **By Hostname** - Separates subdomains (blog.example.com vs [www.example.com](http://www.example.com))
Open a domain or hostname to explore its cited pages. Pagination keeps each page's rank and previous-period comparison consistent across the selected date range.
## The Sources Table
| Column | Shows |
| - | - |
| Source | URL, domain, or hostname |
| Citations | Times cited in responses |
| Top Position | How often cited first |
| Category | News, Blog, Official, Review, Directory, Social, Other |
## Filters
The source data respects all global filters:
* **Brand**: view sources for a specific brand
* **Date Range**: time period for citations
* **Topics**: filter by prompt topic categories
* **Tags**: filter by custom prompt labels
* **Services**: focus on specific AI platforms
* **Countries**: filter by geography
## Source Categories
| Category | Examples |
| - | - |
| Academic | Arxiv, University Websites |
| Analyst & Research | Forrester, G2 |
| Corporate | Company websites |
| Editorial | News Publishers, Independent Blogs |
| Institutional | Government websites |
| Reference | Wikipedia |
| UGC | LinkedIn, Reddit |
| Other | Websites that don't fit in other buckets |
## What to Look For
**Your own site:**
* Are you being cited? Which pages?
* Compare your citation volume to competitors
**Competitors:**
* Which sources cite them but not you?
* What content types perform well?
**Influential sources:**
* Which sites get cited most in your category?
* Potential targets for PR or guest content
## Export
Click **Export** to download source data. Options: Detailed, By Domain, By URL, By Hostname.
## Tips
* If you're not being cited, focus on creating authoritative, publicly accessible content
* Different AI services cite different sources - variation is normal
* Source influence builds over time; content strategy takes months to show results
Exports respect the active view’s text search as well as the selected source filters, even when you choose a different grouping for the exported file.
# Suggested Prompts
Source: https://docs.surfacd.com/docs/suggested-prompts
Let AI generate topic-specific prompts that you can review, accept, or decline before adding to your project.
Suggested Prompts is an AI-powered feature that generates prompt ideas based on a topic you describe. While the onboarding flow generates prompts broadly across your topics, Suggested Prompts lets you drill into specific areas to expand your monitoring coverage.
## How It Works
1. Navigate to your project's **Prompts** tab
2. Click **Suggest Prompts**
3. Select a **Topic** to assign generated prompts to (choose an existing topic or create a new one)
4. Add an optional **description** for more context
5. Define the **target audience** for the prompts
6. Select a **country** and **language**
7. Click **Generate**
Surfacd uses AI to generate a set of relevant prompts based on your topic. These appear with a **Suggestion** status; they are not active until you review and accept them.
Prompt generation runs in the background. You'll see a progress indicator while prompts are being created, and you can navigate away and come back later.
## Reviewing Suggestions
Once generated, suggested prompts appear in your prompts list with a **Suggestion** badge. For each prompt, you can:
* **Accept**: moves the prompt to **Active** status and includes it in future data collection runs
* **Decline**: marks the prompt as **Declined** and removes it from the active view
You can accept or decline prompts individually or in bulk.
## What Happens After Accepting
When you accept a suggested prompt:
* It becomes **Active** and is included in future data collection runs
* A **keyword** is automatically extracted from the prompt text
* The prompt counts toward your project's prompt limit and credit calculations
## When to Use Suggested Prompts
| Scenario | Example |
| - | - |
| Expanding into a new topic area | "AI-powered customer service chatbots" |
| Discovering questions you hadn't considered | "What concerns do enterprise buyers have about cloud migration?" |
| Building coverage for a product launch | "Electric vehicle fleet management for logistics companies" |
| Filling gaps in your prompt library | "Data privacy regulations in healthcare" |
## Tips
* Be specific with your topic description: "CRM for financial advisors" generates better prompts than just "CRM"
* Include your target audience to get prompts that match real buyer questions
* Review all suggestions before accepting, and remove any that are too niche or off-topic for your needs
* Use Suggested Prompts alongside other methods: onboarding for broad coverage, Suggested Prompts for deep dives into specific areas
* Don't worry about duplicates: Surfacd automatically detects and skips prompts that already exist in your project
# Supported Platforms
Source: https://docs.surfacd.com/docs/supported-platforms
Surfacd monitors the AI platforms your buyers actually use. Here is every service we support and what makes each one unique.
Surfacd monitors the major AI platforms that shape how your brand is discovered and recommended. Each platform has its own approach to generating answers, citing sources, and recommending brands, which is why monitoring all of them gives you the most complete picture.
When platforms cite the same web page more than once, Surfacd deduplicates those citations around a canonical URL so source reports, exports, and URL-level opportunity views count the same page consistently.
## Why Monitor Multiple Platforms?
Different AI platforms often give different answers to the same question. A brand that ranks first on ChatGPT may not appear at all on Perplexity. Sources that influence Gemini may have no impact on Copilot. Monitoring all platforms reveals these differences so you can optimise your strategy across the board.
## Platforms
### ChatGPT
**By OpenAI.** The most widely used conversational AI platform.
ChatGPT generates detailed, conversational responses and frequently recommends brands by name. It draws on a broad training dataset and increasingly cites external sources. Its responses tend to be comprehensive and list-based, making it a key platform for brand visibility.
**What Surfacd captures:** Full response text, brand mentions with position, and cited sources.
### Google Gemini
**By Google.** Google's conversational AI assistant.
Gemini provides conversational AI responses with tight integration to Google's search index. It often cites specific web pages and provides nuanced, detailed answers. Brand recommendations can differ significantly from ChatGPT due to Google's distinct data sources and ranking signals.
**What Surfacd captures:** Full response text, brand mentions with position, and cited sources.
### Claude (early access)
**By Anthropic.** Conversational AI assistant with a rapidly growing user base.
**Early access.** Claude is not included in plans by default. Contact support to enable it for your team.
Claude generates thoughtful, well-structured responses and can search the web for current information, citing the pages it draws on. Surfacd queries Claude with web search enabled to mirror how the Claude app behaves, so responses reflect both the model's knowledge and live web sources.
**What Surfacd captures:** Full response text, brand mentions with position, and cited sources.
### Perplexity
**AI-Powered Search Engine.** Combines AI responses with real-time web search.
Perplexity is built as an answer engine with a strong emphasis on source attribution. Every response includes numbered citations linking to the original web pages. This makes Perplexity's source data particularly valuable for understanding which content influences AI recommendations.
**What Surfacd captures:** Full response text, brand mentions with position, and all cited sources with URLs.
### Microsoft Copilot
**By Microsoft.** AI assistant integrated across Microsoft's ecosystem.
Copilot draws on Bing's search index and Microsoft's data partnerships. It provides conversational answers with source links and is increasingly embedded in Microsoft 365, Edge, and Windows. Brands that perform well on Copilot benefit from visibility across Microsoft's entire product ecosystem.
**What Surfacd captures:** Full response text, brand mentions with position, and cited sources.
### Grok
**By xAI.** AI assistant with real-time access to X (Twitter) content.
Grok stands apart by incorporating real-time social media data from X alongside web content. This means brand sentiment, trending discussions, and recent news coverage can directly influence its recommendations. Grok is particularly relevant for brands with active social media presences.
**What Surfacd captures:** Full response text, brand mentions with position, cited sources, and referenced X posts.
### Google AI Mode
**By Google.** Conversational AI experience within Google Search.
AI Mode transforms Google Search into a conversational experience. When users engage AI Mode, Google generates synthesised answers drawing from its search index. This represents a significant shift from traditional search: instead of showing ten blue links, Google provides a single AI-generated answer with embedded references.
**What Surfacd captures:** Full AI-generated response, brand mentions with position, and all referenced sources.
### Google AI Overviews
**By Google.** AI-generated summaries that appear at the top of search results.
AI Overviews (formerly SGE) are the AI-generated summary boxes that appear above traditional Google search results. Not every query triggers an AI Overview, but when they appear, they command significant attention. Understanding whether your brand appears in these overviews is critical as Google continues to expand this feature.
**What Surfacd captures:** AI Overview content (when present), brand mentions, and all cited sources with deduplication.
AI Overviews don't appear for every query; this is normal. When Surfacd collects data for a prompt and no AI Overview is present, that's accurately recorded. This information itself is valuable: it tells you which of your topics trigger AI summaries and which don't.
## Real Interfaces Where Possible
For most platforms, Surfacd interacts with the same consumer-facing interfaces your buyers use. This matters because consumer-facing products frequently use different system prompts, different retrieval sources, and different ranking logic compared to their APIs.
Some platforms are monitored through the model provider's API instead — currently Claude and Grok. These are marked with an **API** badge in the platform selector. API responses come from the same underlying model, with web search enabled where the platform supports it, but can differ from what a user of the consumer app would see.
## Choosing Which Platforms to Monitor
For the most complete picture, monitor all available platforms. If you need to be selective (e.g., for credit management), consider:
| Priority | Platforms | Rationale |
| - | - | - |
| Essential | ChatGPT, Gemini, Perplexity | Highest adoption, broadest coverage |
| Recommended | + Copilot, AI Overviews | Microsoft ecosystem reach, Google search integration |
| Comprehensive | + Grok, AI Mode | Full market coverage including social signals and conversational search |
Use the [Matrix Analysis](/docs/matrix-analysis) with the **Service** dimension to compare your visibility across platforms. This helps you identify where you're strong and where you need to focus.
Only currently active platforms are shown in project setup, project settings, and reporting filter options. If a platform is temporarily unavailable, historical data remains in reports, but it will not be offered for new monitoring until it is active again.
# Topics & Tags
Source: https://docs.surfacd.com/docs/tags-organisation
Topics group your prompts into categories for structured analysis. Tags add flexible labels for cross-cutting filtering and comparison.
Surfacd provides two ways to organise your prompts: **Topics** for primary categories and **Tags** for flexible labelling.
## Topics
### What Are Topics?
Topics are project-level categories that group your prompts by business area. Each prompt belongs to at most one topic, giving your prompt library a clean, structured hierarchy.
Examples of topics:
* Email Marketing, CRM, Sales Engagement, Marketing Automation
* Enterprise Solutions, SMB Products, Partner Integrations
* Data Privacy, Cloud Security, Compliance
### How Topics Are Created
**During onboarding:** After creating your project, Surfacd analyses your brand and generates suggested topics automatically. You can edit names and descriptions, add or remove topics, and set a target audience before prompts are generated for each topic.
**From the Prompts page:** When adding prompts manually or via [Suggest Prompts](/docs/suggested-prompts), use the Topic field to pick an existing topic or create a new one.
**Via bulk actions:** Select prompts and use **Change Topic** to assign or reassign topics in bulk.
**From Manage Topics:** Open **Manage Topics** in the project sidebar to create a topic before assigning prompts to it.
### Managing Topics
The **Manage Topics** page (in the project sidebar, under Manage Tags) lists every topic with its description, prompt count, and creation date. From here you can:
* **Create** a new topic with an optional description
* **Rename** a topic or update its description
* **Delete** a topic after confirming
Deleting a topic never deletes prompts: any prompts still assigned to it are moved to **Uncategorized**, and the confirmation dialog tells you how many prompts that affects. Click a topic's prompt count to review those prompts first.
### Using Topics in Analysis
* **Filter any report** by topic to focus on a specific business area
* **Matrix Analysis:** Topic is a dimension, so you can compare Brands x Topics, Topics x Countries, and more
* **Grouped view:** Toggle the prompts table to display prompts grouped by topic in an accordion layout
* **Uncategorized:** Prompts without a topic appear under "Uncategorized" in filters and grouped views
## Tags
### What Are Tags?
Tags are flexible labels you can apply to any prompt. Unlike topics (one per prompt), a prompt can have multiple tags, making them ideal for cross-cutting dimensions like funnel stage, intent type, or priority.
### Creating Tags
Tags are created as you add them to prompts: type a new name in the Tags field, pick a colour, then confirm. You can also create and edit tags (including colour) from **Manage Tags**.
Each tag has a colour so large prompt libraries are easier to scan. Colours appear on prompt chips, tag dropdowns, and report filters. Existing tags without a colour show as grey.
### Tag colours
Choose from: grey, blue, cyan, purple, pink, red, orange, yellow, green, teal.
CSV import creates tags without a colour (they appear grey). Change the colour later from Manage Tags or when editing a tag.
### Tagging Strategies
Choose an approach that fits your needs:
* **By Funnel Stage:** Awareness, Consideration, Decision
* **By Intent Type:** Best Of, Comparison, How To, Recommendations
* **By Priority:** Core, Growth, Competitive, Exploratory
* **Combined:** Use multiple tag dimensions for richer analysis
### Using Tags in Analysis
* **Filter any view** by tag to focus on specific groupings
* **Matrix Analysis:** Compare Brands x Tags to see which labels each brand dominates
* **Identify gaps:** Find tags where you underperform vs competitors
## Topics vs Tags
| | Topics | Tags |
| - | - | - |
| **Purpose** | Primary prompt categories by business area | Flexible labels for cross-cutting analysis |
| **Relationship** | One topic per prompt | Multiple tags per prompt |
| **Created** | AI-generated during onboarding, editable anytime | Manually created as needed |
| **Best for** | Structuring your prompt library | Adding dimensions like funnel stage or intent |
| **Example** | "Enterprise CRM", "Email Marketing" | "Awareness", "Comparison", "High Priority" |
## Who Can Manage Topics and Tags
What you can change depends on your [team role](/docs/team-settings#members). Project owners can do everything on their own projects.
| Action | Viewer | Member | Admin |
| - | - | - | - |
| See topics and tags, filter reports by them | ✓ | ✓ | ✓ |
| Create, rename and delete topics, and change a prompt's topic | | ✓ | ✓ |
| Add, replace and remove tags on prompts | | ✓ | ✓ |
| Create and edit tags | | ✓ | ✓ |
| Delete tags | | | ✓ |
Buttons for actions your role doesn't allow are hidden. Adding prompts, including copying them to another country, can still create the topics and tags those prompts use.
## Best Practices
* Use **Topics** for your main organisational structure: group prompts by business area or product category
* Use **Tags** for cross-cutting dimensions that span multiple topics
* Every prompt should have a topic; tags are optional enrichment
* Start with 5–10 tags, adding more as needed
* Be consistent with naming for both topics and tags
* Review monthly: merge unused tags, add new topics for emerging business areas
# Taking Action on Your Data
Source: https://docs.surfacd.com/docs/taking-action
Practical strategies for turning AI visibility insights into measurable improvements for your brand.
Data is only valuable when it drives action. Surfacd gives you the visibility. Here's how to turn those insights into results.
## Understanding Your Starting Point
Before taking action, establish your baseline:
1. **Check your Dashboard**: what's your overall visibility score?
2. **Review Rankings**: where do you sit relative to competitors?
3. **Read your Mentions**: scan every captured AI answer (default), then switch to Mentioned Only to focus on how AI describes your brand
4. **Analyse Sources**: which websites are being cited?
This baseline becomes your benchmark for measuring the impact of everything you do next.
## Improving Your Visibility Score
Your visibility score represents how often your brand appears in AI responses. Here are the most effective ways to improve it.
### Create Authoritative Content
AI platforms prioritise content that is:
* **Comprehensive**: covers topics in depth rather than surface-level
* **Authoritative**: published on respected, well-established domains
* **Publicly accessible**: not behind paywalls or login walls
* **Well-structured**: uses clear headings, lists, and data that AI can easily parse
**Action:** Identify topics where your visibility is low (sort prompts by visibility, ascending) and create detailed, expert-level content addressing those questions on your website.
### Target the Sources AI Cites
The **Sources** report reveals which websites AI platforms reference. These are the publications and pages that directly influence AI recommendations.
**Action:**
1. Go to **Sources** → **By Domain** to identify the most-cited publications in your industry
2. Cross-reference with your brand's presence: are you featured on these sites?
3. Prioritise PR, guest content, and partnerships with highly-cited sources
4. Focus on publications where competitors appear but you don't
Use the **Source Categories** breakdown to identify the types of content AI values most. If editorial sites dominate your category, invest in PR. If UGC sources like Reddit and LinkedIn are prominent, focus on community engagement.
### Address Inaccurate Information
AI sometimes surfaces outdated or incorrect information about brands.
**Action:**
1. Review your **Mentions** for any inaccurate descriptions, outdated pricing, or incorrect product details
2. Update the primary source of this information (your website, Wikipedia, key review sites)
3. Monitor over subsequent runs to confirm corrections have propagated
## Competitive Intelligence
### Identify Competitor Strengths
Use **Rankings** and the **Competitor Visibility Chart** to understand where competitors outperform you.
**Action:**
1. Enable the **Competitor Visibility Chart** on the Rankings page
2. Filter by different **Topics** (or **Tags**) to find specific categories where competitors lead
3. Read competitor **Mentions** to understand what AI says about them that it doesn't say about you
4. Analyse their cited **Sources**: are they featured in publications you're missing?
### Spot Emerging Competitors
AI responses surface brands you may not have considered as competitors.
**Action:**
1. Review **Rankings** regularly for new brands appearing in your space
2. Mark emerging threats as **Competitors** to track their trajectory
3. Use the **Matrix Analysis** to compare their performance across services, countries, and topics
## Platform-Specific Strategies
### Differences Across Platforms
The [Matrix Analysis](/docs/matrix-analysis) with **Brand × Service** reveals how your visibility varies across AI platforms.
**Action:**
* **Strong on one platform, weak on another?** Investigate the sources each platform cites, as they may be drawing from different content
* **Consistently low everywhere?** Focus on foundational content and authority building
* **Declining on a specific platform?** Check if that platform has changed its approach and review what sources it now prefers
### Regional Differences
If you monitor prompts across countries, use **Brand × Country** in Matrix Analysis.
**Action:**
* Identify markets where localised content could boost visibility
* Prioritise regional publications and media in underperforming markets
* Ensure product information is accurate and up-to-date for each region
## Tracking Your Progress
### Set Up a Review Cadence
| Cadence | What to Check | Time |
| - | - | - |
| Daily | Latest run completed, scan for major changes | 5 minutes |
| Weekly | Ranking movements, new mentions, source shifts | 15 minutes |
| Monthly | Export data, document trends, plan next actions | 1 hour |
| Quarterly | Strategic review: are your prompts and focus areas still relevant? | 2 hours |
### Measuring Impact
AI visibility improvements take time. Content strategy, PR efforts, and brand building typically show results over weeks and months, not days.
**Track these metrics over time:**
* **Visibility score**: is it trending upward?
* **Rank position**: are you climbing the rankings?
* **Mention sentiment**: is the tone improving?
* **Source citations**: are you appearing in more cited publications?
* **Position distribution**: are you being mentioned earlier in responses?
Use [Exporting Data](/docs/exporting-data) to create regular snapshots for stakeholder reports.
## Reporting to Stakeholders
### Building a Narrative
Surfacd data gives you a clear story for leadership and stakeholders:
1. **The landscape**: "AI platforms now generate brand recommendations. Here's how we compare."
2. **Our position**: "We rank #X overall, with strengths in \[topic] and gaps in \[topic]."
3. **The opportunity**: "By targeting \[specific sources/topics], we can improve our visibility."
4. **The progress**: "Since we started, our visibility has moved from X% to Y%."
### Useful Exports
* **Rankings export** with competitors only: clean competitive positioning overview
* **Matrix export** (Brand × Topic): shows strengths and weaknesses by topic category
* **Sources export** by domain: target list for PR and content efforts
* **Mentions export**: qualitative evidence of how AI describes your brand
## Quick Wins
Ensure product descriptions, pricing, and key details are accurate and publicly accessible. AI often pulls directly from your site.
If your brand has a Wikipedia page, make sure it's accurate and up-to-date. Wikipedia is frequently cited by AI platforms.
G2, Trustpilot, and industry-specific review sites are heavily cited. Encourage reviews and keep your profiles current.
UGC platforms increasingly influence AI responses. Authentic expert contributions in relevant threads build visibility.
# Team Settings
Source: https://docs.surfacd.com/docs/team-settings
Configure your team's members, project defaults, and operational controls.
Access team settings via the **Settings** link in the sidebar. Requires Admin or Owner role.
## General
### Team Name
Your team name appears throughout the application in navigation and headers. Update it anytime without affecting your projects or data.
### Logo and Icon
Upload your company logo and icon to brand your workspace. See [Customising Your Brand](/docs/customising-your-brand) for full details on branding options including colour palettes, logos, icons, and custom domains.
### Primary Colour
Choose a colour palette for buttons, links, charts, and UI accents across your workspace. Nine palettes are available: Blue, Indigo, Purple, Red, Orange, Yellow, Green, Teal, and Slate.
### Default Country
Set a default country for your team. When team members create new projects, this country will be pre-selected, saving time and ensuring consistency.
### Default Prompt Limit
Set the maximum number of prompts allowed per project. This is a team-wide default that controls resource consumption. Individual projects inherit this limit unless overridden.
### User Auto-Provisioning
Automatically add users to your team when they sign in with Google or Microsoft using a matching email domain.
1. Enable the **User Auto-Provisioning** checkbox
2. Choose a **default role** for auto-provisioned users (Admin, Member, or Viewer)
3. Add one or more **email domains** (e.g. `company.com`)
When someone with a matching email domain signs in via OAuth, they receive a pending invitation to your team. They must accept the invitation before gaining access.
Free email domains (gmail.com, outlook.com, etc.) are blocked to prevent unintended access.
### Maximum Schedule Frequency
Control how frequently team members can schedule data collection:
| Setting | Members Can Choose |
| - | - |
| Daily | Daily or Weekly |
| Weekly | Weekly |
This helps manage [credit consumption](/docs/how-credits-work) across the team.
## Members
### Roles
| Role | Capabilities |
| - | - |
| Owner | Full control including ownership transfer and billing |
| Admin | Manage settings, members, and all projects |
| Member | Create, edit, share, and delete any team project; cannot manage team settings |
| Viewer | Read-only access to projects |
### Inviting Members
1. Click **Invite Member**
2. Enter their **name**, **email**, and select a **role**
3. Click **Send Invitation**
The invitee receives an email with a link to accept. They appear as **Pending** until they accept.
### Managing Members
From the actions menu (three dots) on any member row:
* **Change Role**: promote or demote (except the Owner)
* **Resend Invitation**: for pending members who didn't receive the email
* **Transfer Ownership**: make another member the Owner (you become Admin)
* **Remove from Team**: revoke all access immediately
Removing a member immediately revokes their access to all team projects.
## Usage
The **Usage** tab provides a detailed view of credit consumption across your team. See [Usage & Credits](/docs/usage-billing) for full details, or [How Credits Work](/docs/how-credits-work) to understand the credit system.
## Tips
Upload your logo and select your brand colour to make the platform feel like your own. See [Customising Your Brand](/docs/customising-your-brand) for the full guide.
Use the maximum schedule frequency and prompt limits to prevent unexpected credit usage. Review the [Usage](/docs/usage-billing) page regularly.
Assign Viewer roles to stakeholders who only need to see reports, and Member roles to those who actively manage projects.
# Themes & Narratives
Source: https://docs.surfacd.com/docs/themes-narratives
Explore the recurring stories AI platforms tell about your brand, grouped by topic.
A **narrative** is a single recurring story AI tells about your brand, pulled from real responses: "praised for ease of use", "seen as expensive for small teams". A **theme** groups related narratives under a shared topic, such as Pricing or Customer Support. Themes give you the headlines; narratives give you the detail.
## The Themes Tab
Each theme is shown as a card with:
| Element | Shows |
| - | - |
| Sentiment Score | The theme's 0-100 score, with its label |
| Sentiment breakdown | The split of negative, neutral, and positive mentions |
| Narratives | How many narratives sit under the theme |
| % of responses | The share of AI responses where the theme appeared, with trend |
| Surfaced By | Which AI platforms raised the theme |
Search to find a specific theme, or sort by **% of responses**, **Narrative count**, or **Most negative** to surface problems first.
## Theme Detail
Click a theme to open it. The header charts daily mentions by sentiment and summarises the key numbers for the period. Below it, three tabs:
* **Overview** - the narratives within the theme and how they moved, the sentiment split per AI model (useful when one platform frames a topic differently to the rest), the most cited sources, and when the theme was first and last seen
* **Responses** - the AI responses behind the theme, with the relevant excerpts
* **Sources** - the web pages cited in those responses
## The Narratives Tab
The narrative explorer lists every narrative with filters down the side:
* **Search** - find narratives by wording
* **Sentiment** - positive or negative
* **Momentum** - filter by how narratives are moving (see below)
* **Themes** - limit to one or more themes
Sort by **% of responses**, **Largest movement**, **Latest**, or **Most negative**, and switch between card and compact views.
## Momentum
Every narrative carries a momentum badge comparing the selected period to the previous one:
| Badge | Meaning |
| - | - |
| Emerging | Brand-new this period, with no presence in the previous window |
| Surging | Share of responses grew sharply versus the previous period |
| Steady | Roughly flat versus the previous period |
| Cooling | Share of responses fell sharply but the story is still present |
| Dormant | Present last period, gone this one |
Momentum measures movement, not sentiment. A surging narrative can be praise or a growing problem, so check its sentiment too.
## Narrative Detail
Click a narrative to see the full picture:
* **Model Agreement** - how often each AI model stated this narrative. Broad agreement means the story is embedded across platforms, not a one-off
* **Related narratives** - other stories from the same theme
* **Responses** - every response linked to the narrative, with the extracted excerpt
* **Sources** - the pages cited in the responses where the narrative appeared. They aren't tied to the narrative itself, but they show what AI was drawing on in the same answers
* **Lifecycle** - when the narrative was first and last seen
## Export
Click **Export** on the Themes or Narratives tab for an Excel download matching your current filters. Theme and narrative detail pages also export their responses and sources.
## What to Look For
* **Negative narratives with high % of responses** - these shape buyer perception the most, address them first
* **Broad model agreement on inaccuracies** - if every platform repeats the same wrong claim, correct it at the source
* **Sources around negative narratives** - the pages cited alongside them often point to where PR or content effort will pay off
# Usage & Credits
Source: https://docs.surfacd.com/docs/usage-billing
Track credit consumption across your team and projects.
The **Usage** tab in team settings shows how your team consumes credits, with breakdowns by project and a full transaction history. For an overview of how the credit system works, see [How Credits Work](/docs/how-credits-work).
## Credit Overview
The top of the page shows your current usage against your allowance:
* **Credits Used** / **Allowance** (e.g., `1,250 / 10,000` or `1,250 / Unlimited`)
* A visual **progress bar** showing scheduled (reserved) usage
* **Warning indicators** when projected usage approaches your limit
The sidebar also includes a compact credit indicator so you can check your usage at a glance from any page.
## Usage History
The first tab shows a detailed log of every credit transaction.
| Column | Shows |
| - | - |
| Date | When the transaction occurred |
| Project | Which project (clickable link) |
| Credits | Amount consumed |
| Description | Transaction details |
**Filter by type** using the dropdown:
* **All Types**: everything
* **Credits Used**: credits consumed by data collection runs
* **Insufficient Funds**: events where a run couldn't start due to insufficient credits
## Project Usage
The second tab breaks down credit consumption by project.
### Scheduled
All active projects with automated scheduling (Daily or Weekly) — including any that currently reserve no credits.
| Column | Shows |
| - | - |
| Project | Name (clickable) with schedule frequency |
| Prompts | Number of active prompts |
| Services | Number of active AI services |
| Credits/Run | Cost per single data collection run |
| Reserved | Credits reserved for the month |
Pitch projects never appear here because they use no credits.
## Understanding Costs
Each data collection run consumes credits based on:
1. **Number of active prompts** in the project
2. **Number of active AI services** enabled
3. These multiply together: more prompts and services = more credits per run
To estimate monthly costs for a scheduled project:
* Find **Credits/Run** in the Project Usage tab
* Multiply by the frequency multiplier (Daily = 30, Weekly = 5)
For a detailed explanation, see [How Credits Work](/docs/how-credits-work).
## Tips
* Check usage weekly to avoid surprises
* Use the Project Usage tab to identify which projects are most expensive
* Reduce costs by disabling unused services or deactivating low-value prompts
* Set the team's **Maximum Schedule Frequency** in [Team Settings](/docs/team-settings) to control consumption
* If you see an **Insufficient Funds** event, request a new run after credits are replenished