# Actions
Source: https://docs.peec.ai/actions

A prioritized list of ways to improve your AI visibility, with the evidence behind each recommendation and guidance on what to do next.

<img alt="Image" />

**Actions** turn your source and prompt data into a ranked list of specific improvements you can make. Each recommendation shows the evidence behind it, helping you understand where your visibility gaps are, why they matter, and what you can do to address them.

At the top of the page, actions are organized into **Site audit, Owned, and Earned**, with the number of recommendations shown in each. You can also group them by **What to do**, **Earned vs Owned**, or **Topics** to organize your work in different ways.

* **Site audit:** Technical and accuracy fixes that help AI crawlers access and understand your site, such as crawlability issues or blocked content.
* **Owned:** Content published and managed by your brand, including your website and the social or community channels you post to.
* **Earned:** Placements you need to gain on third-party sources, such as editorial and reference sites that AI already relies on.

<Info>
  Actions sits under **Optimize** in the sidebar and is only visible to **owners (company members and project members).** If you don't see it, your account doesn't have owner access to the company or the project.
</Info>

## Working through an action

Actions are ranked by impact, with the highest-impact opportunities at the top. Work through them in order to focus on the changes most likely to improve your AI visibility.

1. **Open the top action:** Click a row to open the full details and understand the recommended work.
2. **Review the evidence:** Start with **Why this matters** to see the supporting data, then check **Competitor evidence** to understand which competitors are gaining the visibility you're missing and which sources are contributing to it. This helps you decide whether the action is worth prioritizing.
3. **Accept or decline:** Click **Accept** to move the action from **New** to **In progress**. If you don't want to pursue it, select **Decline** instead. Declining isn't final: open a declined action and click **Restore** to send it back to **New**, or **Accept** to start working on it.
4. **Execute:** Follow the guidance outlined in **The brief** and mark each step as you complete it.
5. **Mark it Done:** Once you've completed the action, mark it as **Done**. If you started an action but no longer want to continue, select **Cancel** to move it from **In progress** to **Declined**.

<Info>
  Peec automatically refreshes your Actions on a set schedule.
</Info>

<Tip>
  Use the **status filter** above the list to switch between **All statuses**, **New**, **In progress**, **Done**, and **Declined**, making it easier to focus on actions at a specific stage. You can also apply the same action to an entire group at once using the bulk option, such as **Accept all**.
</Tip>

### Writing your own actions

You can also add work Peec didn't suggest. Click **Create action** to write your own, with a title, description, steps, and the page it's about. Your actions sit in the same list as Peec's, with the same statuses and filters, and you can edit them later from the action's details.

<Info>
  You can also create and edit Actions through the [MCP server](https://docs.peec.ai/mcp/tools#create-actions) or the **Customer API**.
</Info>

### Expected outcome

Every action carries a **Relative impact** rating, shown as three bars with a word beside them: **Very low**, **Low**, **Moderate**, **High** or **Very high**. It ranks the action's expected lift against your other actions.

**It's one scale across every kind of action.** A technical fix and a new comparison page are rated the same way, so a High on either means the same thing. The raw numbers underneath aren't comparable between action types, which is why the rating exists.

<Tip>
  Filter by **Models, Topics, Countries, Page types, Source types, Platforms, Owned vs earned,** or **Actions**. Filters combine, and they narrow which actions you see without changing any action's rating.
</Tip>

## What's inside an action

Open an action to see the full details behind the recommendation:

* **Overview:** A short summary of the issue or opportunity.
* **Topic:** The topic the action is relevant to.
* **Models:** The active AI models the action is relevant to.
* **Country:** The tracked country the action is relevant to.
* **Your page:** The URL the action relates to, when it's about a page you own.
* **Why this matters:** Shows the data behind the action, including citation counts, the relevant topic, page type, and time period. For example, *“Competitor comparison pages were cited in 14 conversations about CRM software in the last 30 days, while your brand has no comparison page covering the topic.”*
* **Competitor evidence:** Shows which competitors are performing better for this opportunity and the sources contributing to their performance.
* **The brief:** Provides a suggested content structure when the action involves creating or improving content.
* **What to do:** Provides a step-by-step list of recommended actions that you can check off as you complete them.
* **Expected outcome:** Shows the potential impact of completing the action.
  * **Relative impact:** How this action's impact compares to your other actions.
* **Additional context:** Provides any other relevant information Peec found that supports the action.

### Source types

Actions are also categorized by **source types** connected to the opportunity, helping you understand where you may need to make changes or build visibility.

* **Your pages:** Pages you or your competitors control, such as articles, product pages, listicles, and how-to guides.
* **Editorial:** Third-party articles, guides, comparisons, reviews, and listicles that influence AI responses.
* **UGC:** Forums, Q\&A sites, and other community platforms where audiences discuss brands and industry topics.
* **Wikis & references:** Encyclopedias, glossaries, indexes, and knowledge hubs that AI may rely on for information.
* **Other:** Sources that don't fit into the categories above.

The **Source types** filter covers the third-party ones: Editorial, UGC, and Wikis & references.

## Impact

**Impact** sits under **Actions** and shows whether the work you completed made a difference. While **Relative impact** rates an action before you take it, **Impact** measures the results afterward.

**Impact** sits under **Optimize**, next to Actions, and shows whether the work you completed made a difference. While **Relative impact** rates an action before you take it, **Impact** measures the results afterward.

<img alt="Image" />

A graph shows how your brand performance changes over time, with the option to switch between [visibility](https://docs.peec.ai/metrics/brand-metrics/visibility), [sentiment](https://docs.peec.ai/metrics/brand-metrics/sentiment), [position](https://docs.peec.ai/metrics/brand-metrics/position), and [share of voice](https://docs.peec.ai/metrics/brand-metrics/share-of-voice). It opens on **Visibility** and can be filtered by date range, tag, model, country, and topic.

* **Day markers:** Show when an action changed status on the graph: amber when it moved to **In progress** and green when it was marked **Done**.
* **Action tracker:** Lists the actions connected to those markers. Click an action to open its details beside the graph.

<Info>
  Markers appear in the time period when the status change happened, so weekly or monthly views may combine multiple changes into one marker.

  Peec automatically records when an action changes status. For completed actions, the timestamp reflects when the action was marked **Done**, rather than its full status history.
</Info>


# Ads
Source: https://docs.peec.ai/ads

Identify which brands advertise on the prompts you’re tracking, review their ads, and see which pages those ads point to.

<Frame>
  <img alt="Screenshot 2026 07 16 At 13 13 57" />
</Frame>

ChatGPT now displays sponsored ads within some responses. Even if your brand ranks first organically, a competitor's ad can still appear in the same answer and capture the click.

The **Ads** page shows all ads Peec has captured across your tracked prompts, so you can see who is advertising, what they’re promoting, where they’re sending users, and how often they appear.

<Info>
  Note: Ad tracking is currently available for **ChatGPT** only. If you don't see ads for other AI models, that's because they aren't currently supported.
</Info>

## Ads overview

At the top of the dashboard, you will see:

* **Advertisers in market:** The total number of advertisers we've seen run at least one ad on your tracked prompts.
* **Bidding on your brand:** Advertisers running ads on your branded or comparison prompts.
* **Ad coverage:** Share of your tracked chats that showed at least one ad.
* **Prompts with ads:** The total number of prompts that showed ads, out of all your tracked prompts.
* **Average prompts per advertiser:** The average number of prompts each advertiser runs ads on.

<Info>
  Ads are currently only supported in the **United States,** the **United Kingdom, Canada, Australia, New Zealand, Japan, and South Korea**.

  If you're tracking ChatGPT prompts in other countries, you may see few or no ads because the feature isn't available there yet.
</Info>

Below the KPIs, you'll find two charts:

* **Ad presence over time:** Shows how often ads appeared over the selected period for your chosen brand compared with other advertisers.
* **Ad share:** Advertisers ranked by their ad exposure share. (You can toggle for the **Biggest movers** to show which advertisers gained or lost the most ad share compared with the previous period, helping you spot who's increasing or reducing their advertising.)

The chart will show how many ads appeared each week for your selected brand compared with those for other brands. Use it to see how ad activity changes over time and how much belongs to your brand versus everyone else.

## Advertisers table

<Frame>
  <img alt="Ads Table" />
</Frame>

In the advertisers' table, you will see every brand running ads in ChatGPT for your tracked prompts. You can then toggle between three different views:

* **All advertisers:** one row per advertiser. For each advertiser, you'll see:
  * **Creatives:** The number of unique ads captured.
  * **Topics:** The number of Topics where their ads appeared.
  * **Ad visibility:** Their share of all ad appearances across your tracked prompts.
  * **Spend tier:** An estimated spending level relative to other advertisers (**High**, **Medium**, or **Low**).
  * **Times seen:** The total number of times their ads were captured across chat runs.
* **All ads:** All ad creatives are flattened into a single list.
* **Tracked brands:** The same table, limited to brands you already track.

<Tip>
  Hover over an ad to preview the full creative, including its image and **sponsored label**, or click it to open the source chat. You can also search by advertiser or destination URL, filter by **spend tier,** and export the table to CSV.
</Tip>

If you continue scrolling, you’ll see:

* **Bidding on your brand chart:** This shows the advertisers running ads on your branded and comparison prompts, ranked by how many of those prompts they appear on. Use this view to see which brands are advertising on searches related to your brand.
* **Ads by topics and prompts table:** Here you can find a quick breakdown of where the ads are running based on your topic and prompt setup (you can toggle between these two views at any time).
  * **Topics:** See how ads are distributed across your Topics, including the top advertiser, the number of advertisers, the number of distinct ads, and each Topic’s ad coverage. Expand a Topic to view the prompts tracked within.
  * **Prompts:** View every tracked prompt alongside the advertisers that appeared, the number of ads, ad coverage, and whether your brand was mentioned in the response. Filter by **Mentioned** or **Not mentioned** to quickly find prompts where competitors are advertising but your brand isn’t.

<Info>
  In the Prompts view, you can filter by whether your brand is mentioned.
</Info>

<Frame>
  <img alt="Ads By Topic" />
</Frame>

## Best practices

* **Start with "bidding on your brand":** Ads on your branded and comparison prompts are the ones directly competing for clicks that would otherwise be yours.
* **Use the filter mentioned on the Prompts tab:** Helps you find prompts where a competitor's ad appeared, but your brand wasn't mentioned in the AI response, highlighting opportunities where you're missing both paid and organic visibility.
* **Follow ad coverage over time:** A topic whose ad coverage keeps climbing is one AI is actively monetizing and worth watching before the competition deepens.


# Peec AI for Agencies: Getting started
Source: https://docs.peec.ai/agencies/agency-getting-started



Peec AI is built to help agencies efficiently manage AI visibility tracking across multiple clients. Agency plans are designed for teams managing multiple client projects with varying needs and budgets.

<iframe title="YouTube video player" />

[Watch "Welcome to Peec AI" on YouTube](https://www.youtube.com/watch?v=m_Y-m3nE1ps)

Our **Agency plans** are built for teams managing multiple client projects, each with its own prompts, competitors, and goals. The credit-based system gives you the flexibility to distribute resources across those projects as needed.

Think of **credits as your currency** for allocating prompts and AI models across your client projects.

## Understanding agency plan credits

Each Agency plan includes a fixed number of credits that you can allocate across your client projects. Credits determine how many prompts you can track, how many AI models you can track them across, and how frequently they run.

In the **Projects** tab, you can see how many credits are currently allocated to active customer projects and how many remain available within your plan.

The calculation is straightforward: running **one prompt on one AI model for one day uses 1 credit**. Credits are allocated on a monthly basis, so tracking one prompt on one model every day for a full month allocates **30 credits** to that project.

<Info>
  Peec AI's credit calculation formula:

  **1 prompt x 1 model x 1 day = 1 credit**

  **1 prompt x 1 model x 1 month (30 days) = 30 credits**
</Info>

Consider the following scenario:

**Your plan**: Growth with 25,000 credits in total.

* Client A: 100 prompts × 3 models × 30 days = 9,000 credits allocated.
* Client B: 50 prompts × 2 models × 30 days = 3,000 credits allocated.
* Client C: 25 prompts × 5 models × 30 days = 3,750 credits allocated.

**Total allocated: 15,750 credits**<br />**Remaining: 9,250 credits**

The remaining credits can be allocated to existing projects to track additional prompts or models, or used to create new client projects.

This flexibility lets you decide how to distribute prompts and model coverage across your client projects based on their individual needs.

<Info>
  **Credits aren’t spent or consumed.** Instead, they represent the capacity you allocate to each project based on the number of prompts and models you’re tracking. These allocations adjust automatically as you change your tracking setup.

  Your allocated credits remain in place and **do not reset each month**. You can reallocate them across your projects at any time.
</Info>

## Choosing your plan

Peec AI offers **four** Agency plans, designed to support different client portfolio sizes and levels of AI visibility tracking. Each plan includes a different number of credits, project capacity, and feature access:

* **Essential (10,000 credits):** Designed for smaller agencies and teams getting started with AI visibility tracking while managing an initial client portfolio.
* **Growth (25,000 credits):** Built for growing agencies expanding their AI visibility offering as their client base and tracking needs increase.
* **Scale (65,000 credits):** Designed for established agencies managing larger client portfolios.
* **Comprehensive (custom credits):** Built for agencies offering AI visibility as a core service at a larger scale.


# Managing your projects
Source: https://docs.peec.ai/agencies/managing-your-projects



<iframe title="YouTube video player" />

[Watch "Managing your project for agencies" on YouTube](https://youtu.be/cV3u43Pittg)

Managing your client projects in Peec is simple. From the **Projects** tab, you can create new projects, adjust tracking for existing clients, manage their setup, or delete projects you no longer need. Whether you’re onboarding a new client or expanding an existing project, you can manage it all from one place.

## Creating projects

In the **Projects** tab, you can create both **Customer** and **Pitch** projects in just a few clicks. Create a **Customer project** when onboarding a new client, or set up a **Pitch project** for a prospect who wants to explore Peec before committing.

### Creating a customer project

To create a **Customer project**:

1. Go to **Settings → Projects** in the sidebar.
2. Click **Add new project**.
3. Select **Customer project**.
4. Fill in the required project information.
5. Choose the number of prompts you want to track. The summary will automatically update to show how many credits are required based on your selection.
6. Select the AI models you want to track.
7. Click **Continue**.

<Frame>
  <img alt="Creatingnewproject Agency 1" />
</Frame>

### Creating a pitch project

To create a pitch project:

1. Navigate to **Projects** in the side panel
2. Click **Add new project** in the top-left corner or at the top-right of the projects table
3. Select **Pitch project** from the modal
4. Enter the relevant details
5. Click **Add pitch project**

<Frame>
  <img alt="Creating Pitch Project 1" />
</Frame>

## Adjusting your client projects

In the Projects tab, you can easily adjust tracking settings, such as the number of prompts and the models, for each project individually, as well as edit each project's details.

### Changing prompt limit (Max. Prompts)

You can easily adjust how many prompts each project track should have in the **Projects tab** using the project table.

To do this:

* Navigate to the **Projects tab** and locate the project you want to adjust
* Click the box next to the active prompt (in the **Active / Max Prompts** column)
* Enter a new value that is allowed within your credit limit
* Click anywhere else on the screen to save the changes

The credits used column will increase in credits as soon as you increase the number of prompts in your project. If you don’t use all allocated prompts for a project, your used credits will be lower than your assigned credits.

Use this information to optimize your usage and identify where you can reduce prompt limits, freeing up credits for other projects.

<Frame>
  <img alt="Prompt Adjusting 1" />
</Frame>

### Changing AI models

You can choose which AI models you want to track for a given project. You're not locked into tracking all prompts across all models if that's not something you need.

If one client only requires tracking visibility on ChatGPT, while another needs comprehensive coverage across all three platforms, you can choose which AI models to run for each project. You can adjust this in the **Projects** table as well:

* Navigate to the **Projects** tab in the sidebar
* Find the project you want to update
* Select the **Models** box in the project to open up the selector modal
* Switch models or turn off the ones you don’t need
* Click **Update**

<Frame>
  <img alt="Adjusting Models Agencies" />
</Frame>

The system will automatically either assign more credits or free up credits from the project to your overall credit pool.

### Converting pitches to customer projects

If you have a pitch project that you would like to start tracking on a daily basis for one of your clients, you can easily convert it into a customer project in a few simple clicks.

To convert the pitch project:

* Navigate to the **Projects** tab in the side panel
* At the top-left of the table, click on **Pitch**
* Locate the project you wish to convert
* Click on the three dots at the far right of the table
* Click on **Convert to customer**

You will then be prompted to adjust the project settings, such as models and the exact number of prompts that you would like to track.

<Frame>
  <img alt="Pitch Customer Convert 1" />
</Frame>

### Download chats

If you are looking to download a full data set of all chats that have been generated so far for your project, you can also do this in the **Projects tab**.

To download the chats:

* Navigate to the **Projects tab** in the side panel
* Click on the three dots at the far right
* Click on **Export Chats**
* From there, a model will open, and you can click on **Generate Export**

<Frame>
  <img alt="Downloadingchats Agency" />
</Frame>

## Pausing your project

You can pause a client project when you no longer need to track it continuously, but still want to keep it. You can still review the data and resume it later.

Pausing a project stops all prompts within it, meaning that the project will not collect any data until it is resumed. Any data that would have been collected during the pause cannot be recovered, so be sure before pausing a project. Once the project is resumed, prompts will resume running, and new data will appear.

The allocated credits will no longer count toward your limit and can be reassigned to other projects. When you resume, you will need to re-allocate credits.

You can pause a project by:

* Clicking on the three dots for the project you wish to pause
* Click on **Pause Project** and confirm your choice

To resume it, simply:

* Click once again on the three dots
* Click on **Resume Project**
* Make sure you have the required prompts available, and click on **Resume**

<Frame>
  <img alt="Pausing Project Agency" />
</Frame>

## Monitoring credit usage and allocation

Regularly checking your credit usage helps you stay ahead of capacity limits and make the most of your plan.

**What to check:**

* **Total allocation vs. available capacity:** Check your **Projects** tab to see whether you're approaching your credit limit or have room for more customer projects, AI models, or prompts.
* **Per-project allocation:** Check whether each client receives sufficient tracking to deliver meaningful insights and identify those that are underutilizing their allocated prompts.

**When to reallocate:**

* A client engagement is ending
* A high-priority client needs expanded coverage
* You onboard a new client

### How to upgrade your plan

As your agency grows or clients’ needs change, you can adjust your total credit capacity by upgrading or downgrading your plan. Moving between tiers is straightforward and gives you immediate access to your new credit allocation and project slots.

You can easily upgrade your plan via the **Billings** page:

1. Navigate to the **Billings** page in the side panel.
2. Select the plan you want to upgrade to.
3. Complete the checkout flow.

Your existing client projects and data remain intact when you change tiers. The only difference is that your total credit capacity and available project slots adjust to match your new plan.

### How to downgrade your plan

Contact [support@peec.ai](mailto:support@peec.ai) to find the best solution for downgrading your plan.

<Info>
  **Note:** Upgrades are always prorated by day. This means you only pay for the days you're in the new subscription tier.

  Downgrades happen at the end of your current billing cycle.
</Info>


# Understanding credits
Source: https://docs.peec.ai/agencies/understanding_credits

How agencies can use credits to allocate prompts and models to their projects

<iframe title="YouTube video player" />

[Watch "Pricing Update: More value for everyone." on YouTube](https://youtu.be/yzoc-MOhUUY)

Credits determine how many prompts and AI models you can track across your client projects. You can change the number of prompts and the models you want to track them on, but not credits. Instead, they are automatically assigned to the project based on the other two variables.

<Info>
  Peec AI's credit calculation formula:

  **1 prompt x 1 model x 1 day = 1 credit**

  **1 prompt x 1 model x 1 month (30 days) = 30 credits**

  On the **Scale** and **Comprehensive** plans, you can switch projects to **weekly tracking**, which uses one-third of the credits required for daily tracking.
</Info>

For example, tracking the prompt **“What’s the best CRM for small businesses?”** daily across three AI models (**ChatGPT, Claude, and Gemini**) for a full month would allocate **90 credits**:

**1 prompt × 3 AI models × 30 days = 90 credits**

## Managing your credits

### Usage overview

You can see how many credits are available and how many are currently allocated to active customer projects under **Projects → Usage**.

**Usage** shows:

* The total number of credits currently allocated.
* The number of credits still available on your plan.
* A color-coded breakdown showing how your credits are distributed across projects.

Hover over each colored section to see the credits allocated to a specific project. You can also find the same information in the project table below.

When creating a new project, you don’t need to calculate the required credits yourself. Peec automatically calculates the allocation based on the prompts, models, and tracking frequency you select.

<img alt="Image" />

### Project table

The project table gives you a quick overview of all projects in your account, organized into **Customer** and **Pitch** projects.

From here, you can manage how many prompts and models each project tracks, or delete projects you no longer need.

<img alt="Image" />

The **Projects** table shows:

* **Project name:** The internal name used to identify each project.
* **Domain:** The domain connected to the project.
* **Prompts:** The number of **Used** and **Allocated** prompts for each project.
* **Models:** The AI models currently being tracked.
* **Credits:** The number of **Used** and **Allocated** credits based on the project’s prompts, models, and tracking frequency.
* **Frequency:** How often the project runs. **Daily** runs your prompts every 24 hours. On **Scale** and **Comprehensive** plans, you can switch between daily and weekly tracking.
* **Created:** The date the project was created.
* **Status:** Whether the project is a **Customer**, **Pitch**, or **Pitch Ended** project.
* **Settings:** Options to update brand details, adjust tracking settings, or delete the project.

<Info>
  This view also applies to the Pitch project under the **Pitch tab**.
</Info>


# Agent
Source: https://docs.peec.ai/agent

Explore your Peec data by asking questions in plain language and get answers with charts generated for you.

<iframe title="YouTube video player" />

The Agent makes it easier to explore your Peec AI data without jumping between pages or stacking multiple filters. Ask a question in plain language, and it works through your tracked data to return the answer with a chart or list already built.

<Info>
  Agent only works with your own Peec data, so it isn't a general-purpose chatbot. It's also separate from **Agent Analytics**, which tracks AI crawler activity on your website, and **Chats**, which contains the raw AI responses generated from your tracked prompts.
</Info>

## How to ask

<img alt="Image" />

Switch the sidebar to the **Agent** tab to open the panel next to whatever you're viewing. You can also start from where you are: click **Ask AI** on a chart, or press **⌘K** / **Ctrl+K** and hit **Tab** to turn your search into a question.

Type your question in plain language. There's no special syntax or commands to learn.

The Agent understands the context of the page you're viewing, including the selected brand, domain, prompt, date range, and filters. This means you can ask questions like **"Why did this drop?"** without having to explain what you're referring to.

Three shortcuts in the composer help you add context or start from something already available:

* `/` Opens the **Skills** catalog. Choose a skill to use as the starting point for your conversation.
* `@` References a chart, metric, or table directly in your question.
* `+` Opens the same options in browse mode, starting with **Skills** and **Charts & metrics**.

<Info>
  An `@` reference hands the Agent that chart along with its data, so you don't need to describe which one you mean. The Agent can also see what's on your current page, so you can ask about what's on screen without adding a reference.
</Info>

<Tip>
  **Skills** are ready-made analyses that answer common questions about your Peec data. Browse them as cards or in a list, search for the one you need, then pick one to start a conversation with that analysis. You can also create your own skills for analyses you run often.<br /><br />Use the **arrow keys** to browse the options, **Enter** to select one, and **Esc** to dismiss.
</Tip>

### Choosing a quality tier

The **Quality** picker in the composer sets how much work the Agent puts into a chat:

* **Normal:** The fastest responses at the lowest usage. This is the default.
* **High:** More reasoning, at about twice the usage.
* **Max:** The most capable model, at about three to five times the usage.

The tier is saved with the chat, and your last choice becomes the default for your next new chat.

## How the Agent responds

The answer appears as the Agent works through your question, showing its progress, the steps it's taking, and the tools it's using along the way.

Results can appear in different formats depending on your question:

* **Charts:** Visualized from the data the Agent queried.
* **To-do lists:** Turn the answer into a list of next steps.
* **Multiple choice:** Lets you choose between options when the Agent needs more input to continue.

While the Agent is working, the send button becomes **Stop**. On the latest answer, use the controls beneath it to copy the response or retry the question.

<Tip>
  Conversations started in the panel can be opened on the full-page view with **Open in Agent** when you need more space. Your sessions are saved, so you can return to them later.
</Tip>

## Managing approvals

The Agent can read and analyze your data without approval. Any action that makes a change, such as creating a brand, prompt, topic, or tag, is shown to you first and only happens once you click **Approve**.

There are two ways to reduce approval steps when you want to work faster:

* **Auto:** The toggle in the composer approves actions for the rest of the current chat. **Always allow**, in an approval's options menu, turns on the same toggle.
* **Auto-approve actions:** On the **Behavior** page in the sidebar, this makes **Auto** the starting point for your new chats.

<Info>
  Auto-approve covers every action that would otherwise ask, including connector tools set to **Ask**. Tools set to **Never** stay unavailable to the Agent. Leave it off if you'd rather see every change before it lands.
</Info>

## Giving the Agent context

Context is what the Agent knows before you type anything, so you don't have to repeat it in every chat. Set it on the **Context** page in the sidebar, at three levels:

* **User context:** Notes about you that follow you into every project. Add, edit, or delete them, up to 100.
* **Project context:** Applies to this project only. Only project owners can edit it.
* **Company context:** Applies to everyone in your company, across every project. Only company owners can edit it.

The Agent follows project and company context unless you tell it otherwise in the chat. Each holds up to 4,000 characters, and its switch turns it off without deleting it.

<Info>
  The Agent saves notes about you on its own during a chat, without asking. If you own the project or the company, it can also propose an update to that context when you share a lasting fact or instruction about it, and the update goes through an approval like any other change.
</Info>

## Connecting your tools

<img alt="Connectors" />

Connectors let the Agent use tools from products you already work in, such as **Notion**, **Linear**, **HubSpot**, **PostHog**, or **Webflow**. To add one:

1. Open **Connectors** in the sidebar, then search for the product or browse the catalog by category.
2. Pick it, choose where it's **Available in**: **All my projects** or only the current project, and click **Continue**.
3. Sign in with your own account for that product.

Once it's connected, the product's dialog shows your account and its tools:

* Each tool is set to **Always allow** (runs without asking), **Ask** (asks before each use), or **Never** (hidden from the Agent). Read-only tools start on **Always allow** and the rest on **Ask**.
* The connection's menu changes which projects it's available in, reconnects it, or disconnects it.

<Info>
  Connections are personal. Each one uses your own login, and nobody else in the company can use yours. You can have up to 10.
</Info>

## Using the Agent outside of Peec

The Agent uses the same tools as the **Peec MCP server**, so you can use or automate the same analyses outside the platform. Follow the [MCP documentation](/mcp/introduction) to set it up in Claude, Cursor, or any other MCP client.


# AI referrals
Source: https://docs.peec.ai/ai-referrals



AI Referrals shows the website traffic your brand gets from AI assistants, connected directly to your Google Analytics 4 (GA4) property. While the rest of Peec AI tracks how often you are mentioned or cited inside AI responses, AI Referrals tracks what happens next: whether that visibility turns into visits to your site, and whether those visitors engage with your content.

<img alt="Cleaned" />

AI Referrals lives inside **Agent Analytics**, alongside Crawl Insights and Crawlability. The distinction between them: AI Referrals covers human visits arriving from AI assistants, while Crawl Insights covers bot activity.

## Overview

The Overview tab gives you a quick snapshot of your AI-referred traffic, including which AI assistants drive the most visits to your website.

* **KPI cards:** Total Sessions, Conversions, Conversion rate, Engagement rate, and Revenue.
* **AI traffic:** A line chart broken out by AI assistant (ChatGPT, Copilot, Perplexity, Gemini, Claude, Deepseek, and others), with Daily, Weekly, and Monthly granularity toggles and a metric selector.
* **Breakdowns:** AI referral metrics by source, landing page, country, and device.

<img alt="Cleaned2" />

<Info>
  AI Referrals combines Google Analytics 4's native AI-assistant classification with Peec's own regex-based detection, so referrals are captured even where GA4's default grouping might miss them.
</Info>

<Tip>
  Conversions, Conversion rate, and Revenue only populate for accounts with the relevant GA4 setup: key events and/or e-commerce tracking configured. Without that, these fields show as empty.
</Tip>

### Metrics

**Sessions:** A session is a visit to your website that begins when a user arrives and ends after 30 minutes of inactivity or at midnight. It can include multiple page views and events. In this report, only sessions attributed to an AI assistant are counted.

**Session starts:** A session\_start event in GA4 is an automatic event that signals the beginning of a user's active visit to your website. This is another proxy for referred visits, and the two commonly show somewhat different values. One reason is that GA4 sometimes registers a session but fails to log the start event.

**Conversions:** A conversion is a key event. A key event in GA4 is a user interaction you define as important: a purchase, a lead generation event like submitting a contact or sign-up form, or a newsletter sign-up. What counts as a conversion here depends on what you designate as a key event in your GA4 account.

**Conversion rate:** Conversion rate is the percentage of sessions with one or more conversions. In GA4, this is called the session key event rate. You must mark the event you want to track as a key event, otherwise this metric shows no data.

**Engagement rate:** Engagement rate is the percentage of sessions that are engaged sessions. A session counts as engaged if any of these are true:

* It lasts 10 seconds or longer.
* It has one or more conversion events.
* It has two or more page views.

**Avg. engagement time:** Average engagement time is the average length of time your website was in focus in the user's browser.

**Revenue:** Purchase revenue is the total revenue from completed transactions, minus any refunds. A value appears here if your GA4 property includes purchase revenue.

## Details

The Details tab breaks AI-referred traffic down further, in two parts: **Channels** and **Landing pages**.

<img alt="Newdetailsaireferral" />

### Channels

Shows where AI-driven traffic sits in the overall channel mix, and flags the channels that likely contain AI traffic Peec AI cannot measure directly:

* **AI Assistants:** The AI-referred sessions shown throughout this feature.
* **Organic Search:** Google AI Overviews and AI Mode results are classified as organic search by GA4, not as AI referral, so this channel likely contains AI-driven visits that do not show up under AI Assistants.
* **Direct:** Mobile AI apps, or links opened from an AI tool that do not pass a referrer header, land here instead of under AI Assistants.
* **Paid Search:** Traffic from ads on search engine sites, shown for comparison.

### Breakdown

A detailed breakdown of AI-referred traffic and engagement for each landing page. Toggle between URLs and Paths.

**Event page:** This table view shows only event-scoped occurrences and metrics, such as Events, Session starts, Conversions, and (if available) Revenue. These map cleanly to individual host and path combinations.

**Session path:** This table view shows a mix of session-scoped and event-scoped occurrences and metrics: Sessions, Session starts, Engagement rate, Avg. engagement time, Conversions, Conversion rate, and Revenue. If your GA4 property spans multiple subdomains, or domains that share the same path, metrics are aggregated across those domains at the path level; open the dropdown to see certain metrics broken down by host.

**Why metrics differ across these views**

In the Event page breakdown, the session start and other events, including key events (conversions) and revenue, are directly attributable to that URL. In the Session path breakdown, the values are scoped to the page Google attributed the session to. So a transaction may have taken place on another URL within the same session that is attributed to that landing page.<br />

<Tip>
  Use the **Landing pages** table to see which pages turn AI visibility into visits, not just citations. This represents the minimum AI-driven traffic captured, since some AI referrals are not always attributed to AI by Google Analytics.
</Tip>

## Settings

Manage the Google Analytics connection powering your AI referrals data.

* **Connection:** The Google Analytics account, property, and web data stream this project reads from. Shows the connected Google account email, the GA4 property (with its account name), and the data stream (with its measurement ID).
* **Reauthentication:** Invalidates the stored access and re-links the Google account, keeping the same property and stream.
* **Danger zone:** Permanently deletes all AI referrals data and removes the integration.

## Connecting your data

To get started, go to **AI Referrals** and connect your Google Analytics account through Google OAuth. Then select the GA4 property you want to connect. Peec AI supports one GA4 property per project. To switch to a different property later, reconnect it from **Settings**.

## Tracked AI assistants

| **Source domain** | **AI Assistant** | **Platform** |
| :- | :- | :- |
| [chatgpt.com](http://chatgpt.com) | ChatGPT | OpenAI |
| [chat.openai.com](http://chat.openai.com) | ChatGPT | OpenAI |
| [claude.ai](http://claude.ai) | Claude | Anthropic |
| [gemini.google.com](http://gemini.google.com) | Gemini | Google |
| [bard.google.com](http://bard.google.com) | Gemini | Google |
| [perplexity.ai](http://perplexity.ai) | Perplexity | Perplexity |
| [copilot.microsoft.com](http://copilot.microsoft.com) | Copilot | Microsoft |
| [copilot.com](copilot.com) | Copilot | Microsoft |
| [copilot.cloud.microsoft](http://copilot.cloud.microsoft) | Copilot | Microsoft |
| [edgeservices.bing.com](http://edgeservices.bing.com) | Copilot | Microsoft |
| [link.edgepilot.com](http://link.edgepilot.com) | Copilot | Microsoft |
| [grok.com](http://grok.com) | Grok | xAI |
| [meta.ai](http://meta.ai) | Meta AI | Meta |
| [you.com](http://you.com) | You.com | You.com |
| [chat.mistral.ai](http://chat.mistral.ai) | Le Chat | Mistral AI |
| [chat.deepseek.com](http://chat.deepseek.com) | Deepseek | DeepSeek |
| [duck.ai](http://duck.ai) | Duck.ai | DuckDuckGo |
| [iask.ai](http://iask.ai) | iAsk | IAsk AI |
| [phind.com](http://phind.com) | Phind | Phind |
| [poe.com](http://poe.com) | Poe | Quora |
| [hey.pi.ai](http://hey.pi.ai) | Pi | Inflection AI |
| [huggingface.co](http://huggingface.co) | Hugging Face | Hugging Face |
| [consensus.app](http://consensus.app) | Consensus | Consensus |
| [andisearch.com](http://andisearch.com) | Andi | Andi |
| [felo.ai](http://felo.ai) | Felo | Felo Search |
| [lmarena.ai](http://lmarena.ai) | Arena | Arena Intelligence |
| [arena.ai](http://arena.ai) | Arena | Arena Intelligence |
| [openrouter.ai](http://openrouter.ai) | OpenRouter | OpenRouter |
| [monica.im](http://monica.im) | Monica | Monica AI |
| [sider.ai](http://sider.ai) | Sider | Sider.AI |
| [chat.baidu.com](http://chat.baidu.com) | Ernie | Baidu |
| [ernie.baidu.com](http://ernie.baidu.com) | Ernie | Baidu |
| [yiyan.baidu.com](http://yiyan.baidu.com) | Ernie | Baidu |
| [doubao.com](http://doubao.com) | Doubao | ByteDance |
| [chatglm.cn](http://chatglm.cn) | ChatGLM | Zhipu AI |
| [kimi.ai](http://kimi.ai) | Kimi | Moonshot AI |
| [kimi.com](http://kimi.com) | Kimi | Moonshot AI |
| [tongyi.aliyun.com](http://tongyi.aliyun.com) | Qwen | Alibaba |
| [tongyi.com](http://tongyi.com) | Qwen | Alibaba |
| [qianwen.com](http://qianwen.com) | Qwen | Alibaba |
| [qwen.ai](http://qwen.ai) | Qwen | Alibaba |
| [chat.qwenlm.ai](http://chat.qwenlm.ai) | Qwen | Alibaba |
| [ying.baichuan-ai.com](http://ying.baichuan-ai.com) | Baichuan | Baichuan Inc |
| [yuanbao.tencent.com](http://yuanbao.tencent.com) | Yuanbao | Tencent |
| [chat.z.ai](http://chat.z.ai) | Z.ai | Zhipu AI |
| [agent.minimax.io](http://agent.minimax.io) | MiniMax | MiniMax |
| [adot.ai](http://adot.ai) | A. | SK Telecom |
| [ai.ionos.de](http://ai.ionos.de) | IONOS | IONOS |
| [alexaplus.com](http://alexaplus.com) | Alexa+ | Amazon |
| [app.sigmabrowser.com](http://app.sigmabrowser.com) | Sigma | SigmaBrowser |
| [askgpt.app](http://askgpt.app) | AskGPT | AskGPT |
| [blackbox.ai](http://blackbox.ai) | BLACKBOX.AI | BlackBox |
| [chatbotapp.ai](http://chatbotapp.ai) | Chatbot App | Chatbot App |
| [chathub.gg](http://chathub.gg) | ChatHub | ChatHub |
| [easemate.ai](http://easemate.ai) | EaseMate AI | EaseMate AI |
| [exa.ai](http://exa.ai) | exa | Exa Labs |
| [metaphor.systems](http://metaphor.systems) | exa | Exa Labs |
| [galaxy.ai](http://galaxy.ai) | Magica | GalaxyAI |
| [magica.com](http://magica.com) | Magica | GalaxyAI |
| [aymo.ai](http://aymo.ai) | Ayimo.AI | Ayimo AI |
| [liner.com](http://liner.com) | Liner | Liner |
| [getmerlin.in](http://getmerlin.in) | Merlin | Foyer Tech Inc. |
| [glbgpt.com](http://glbgpt.com) | GlobalGPT | Future Share LLC. |
| [go.welt.de](http://go.welt.de) | WELTgo! | Axel Springer |
| [hey.bild.de](http://hey.bild.de) | Hey\_ | Axel Springer |
| [intric.ai](http://intric.ai) | intric | Intric AB |
| [jan.ai](http://jan.ai) | Jan | Menlo |
| [magai.co](http://magai.co) | Magai | SoVisual.co LLC |
| [mammouth.ai](http://mammouth.ai) | MAMMOUTH | Mammouth AI |
| [ninjachat.ai](http://ninjachat.ai) | ninjachat | NinjaChat AI |
| [quillbot.com](http://quillbot.com) | quillbot | Learneo |
| [rogo.ai](http://rogo.ai) | rogo | ROGO AI |
| [scout.yahoo.com](http://scout.yahoo.com) | Yahoo Scout | Yahoo |
| [teamai.com](http://teamai.com) | TeamAI | TeamAI |
| [thinkany.ai](http://thinkany.ai) | ThinkAny | ThinkAny |
| [typingmind.com](http://typingmind.com) | TypingMind | TypingMind |
| [venice.ai](http://venice.ai) | Venice | Venice AI |
| [writingmate.ai](http://writingmate.ai) | Writingmate | Writingmate |
| [yeschat.ai](http://yeschat.ai) | YesChat AI | YESCHATAI |

## Privacy policy

To read our privacy policy, see the [<u>Privacy Policy for Peec AI</u>](https://peec.ai/legal/privacy-policy).


# Create Actions
Source: https://docs.peec.ai/api-reference/actions/create-actions

https://api.peec.ai/customer/v1/openapi/json post /actions/create
Record work the customer decided to do themselves as actions, in the same shape as the ones Peec generates, so they sort, filter and move through the same statuses. The kind picked decides an action's type and group. The linked topic and prompts are resolved against the project, and an item naming one it does not hold lands in `rejected` on its own — the batch never fails as a whole.



# Delete Actions
Source: https://docs.peec.ai/api-reference/actions/delete-actions

https://api.peec.ai/customer/v1/openapi/json post /actions/delete
Remove actions the customer wrote themselves. A generated action reads here exactly as a missing one does and lands in `skipped`: those are declined or dismissed through the status endpoint instead, so the list keeps a record of what Peec suggested and the customer turned down.



# Get Action
Source: https://docs.peec.ai/api-reference/actions/get-action

https://api.peec.ai/customer/v1/openapi/json post /actions/detail
One action in full: what to do, the fields the customer owns on it — notes, priority, assignee, due date, tags and repeat — the steps to work through, the content brief when there is one with its sections, the competitor demand behind it, the prompts it affects and the terms competitors use on the topic. A site audit action carries no brief and no opportunity, and its description and steps are the whole fix. An id this project has no published action for is a 404, whether it belongs to another project, to an action type this API does not publish for the project, or to nothing at all. A content optimisation carries its article, suggestions and score on the optimize content endpoint instead.



# List Action Platforms
Source: https://docs.peec.ai/api-reference/actions/list-action-platforms

https://api.peec.ai/customer/v1/openapi/json post /actions/platforms
The third-party sites a project has actions on, as values for the action list's `platforms` filter. A platform is whichever domain AI engines cite for this brand, so the set is per project and open-ended. Own-site actions carry no platform and are absent here.



# List Actions
Source: https://docs.peec.ai/api-reference/actions/list-actions

https://api.peec.ai/customer/v1/openapi/json post /actions/list
The project's actions, the ones Peec generated and the ones the customer wrote themselves alike: what to do, on which page or site, and how much impact it is expected to have if it is done. `created_by` says which of the two an action is, and only a customer's own can be deleted or reshaped. Filters combine with AND, except `targets`, `groups`, `archetypes` and `platforms`, which combine with OR across the four. The action detail endpoint carries a single action's steps, brief, evidence and impacted prompts.



# Set Action Step Completion
Source: https://docs.peec.ai/api-reference/actions/set-action-step-completion

https://api.peec.ai/customer/v1/openapi/json post /actions/steps/completion
Record which of an action's steps are done. Each entry names one action and either sets `completed` for every step it holds, or lists the steps to write; a step in turn either sets `completed` for all of its options or names them individually, each with its own value, so one call can tick some and untick others. An action is all or nothing: anything Peec cannot apply leaves every step on it untouched and comes back under `skipped` or `rejected`, so a partly-written action is never a state you have to read back. Other actions in the same call are unaffected. The action's own status is never changed by this endpoint, including when every step on it is complete. An action that is already deleted reads as absent unless the key is a platform admin one. A content optimisation is reachable only on a project with content optimisation enabled; elsewhere its id is returned in `skipped`.



# Update Action Status
Source: https://docs.peec.ai/api-reference/actions/update-action-status

https://api.peec.ai/customer/v1/openapi/json post /actions/status
Move actions to a status by id: accept, reject, complete, delete, or send one back to `PENDING`. Ids the project publishes no action under are returned in `skipped` — the batch never fails as a whole. An action that is already deleted reads as absent unless the key is a platform admin one. A content optimisation is reachable only on a project with content optimisation enabled; elsewhere its id is returned in `skipped`.



# Update Actions
Source: https://docs.peec.ai/api-reference/actions/update-actions

https://api.peec.ai/customer/v1/openapi/json post /actions/update
Rewrite the fields a customer owns, on actions they wrote or ones Peec generated. An edit is stored beside the generated wording rather than in it, so a regeneration cannot discard it. Only a customer's own action can change shape: the type and group of a generated one say what Peec found, and an item trying to move them lands in `rejected`. A field the item leaves out keeps what it held; `null` clears the ones that can be cleared, and an item naming no field at all is rejected rather than recorded as an edit. Ids the project publishes no action under are returned in `skipped` — the batch never fails as a whole. A content optimisation is reachable only on a project with content optimisation enabled; elsewhere its id is returned in `skipped`.



# Get Agent Readiness
Source: https://docs.peec.ai/api-reference/agent-analytics/get-agent-readiness

https://api.peec.ai/customer/v1/openapi/json get /agent-analytics/readiness
How ready the project's website and its competitors' websites are for AI agents, from Peec's agent readiness audit.

Each site gets a level from 0 to 5. A level is reached when every gate check of that level and of every level below it passes, so `next_level.blocking_check_ids` lists what to fix next. Each check also reports its own outcome, including the hygiene and emerging-standard checks that never block a level.

Reading this endpoint never starts an audit. A domain without an audit completed in the last 90 days returns `audit: null`.



# Get AI Referrals
Source: https://docs.peec.ai/api-reference/agent-analytics/get-ai-referrals

https://api.peec.ai/customer/v1/openapi/json get /agent-analytics/google-analytics/referrals
AI-referral traffic from the project's connected Google Analytics property, scoped to the hosts the project owns and to referrals from AI assistants. There is no way to ask this endpoint for non-AI traffic.

To list the values a dimension takes, pass it as the only `group_by` and read the rows — that is how you discover event names, countries, pages and the assistants that actually sent traffic. When populating a filter, do not filter by the dimension you are listing, or the options the user has not already picked disappear.

Metric definitions, because the names are shorter than the meanings:
- `events`: GA4 event count.
- `session_starts`: GA4 `session_start` events, which is not GA4's `sessions` metric. Most are visits that entered on the site; the rest resumed there after idling past GA4's session timeout. It cannot be combined with `group_by=event_name`.
- `conversions`: GA4 key events, so one visit can contribute several, and which events count follows whatever the property marked as a key event.
- `revenue`: GA4 purchase revenue in the property's reporting currency, returned as `currency`.

Unknown dimension values come back as `(not set)`. It is a real row, and the free-string filters (`sources`, `devices`, `event_names`, `mediums`) accept it back; `countries` does not, because it takes ISO codes only. Figures are a lower bound on AI referrals: only referrer-visible traffic reaches GA4, so native apps and no-referrer policies land as Direct, and Gemini is often folded into Organic Search.



# List Referral Sources
Source: https://docs.peec.ai/api-reference/agent-analytics/list-referral-sources

https://api.peec.ai/customer/v1/openapi/json get /agent-analytics/google-analytics/list-referral-sources
Every AI assistant Peec can attribute referral traffic to, whether or not this project has seen traffic from it — one row per referrer host, so an assistant reachable on several hosts appears once per host. Use `assistant` for the `assistants` filter on the referrals endpoint, and `source` to recognise a raw host in its results. The list is maintained by hand and reviewed quarterly, so a brand-new assistant may be missing.



# Create Brand Perception Attribute Clusters
Source: https://docs.peec.ai/api-reference/brand-perception/create-brand-perception-attribute-clusters

https://api.peec.ai/customer/v1/openapi/json post /brand-perception/attribute-clusters/create
Add custom attributes to the project's brand-perception market view, the same edit the Add attribute button makes. Each new attribute starts with no terms; a top-of-funnel run is queued for the batch so its market prominence scores populate within a few minutes. A project holds at most 10 custom attributes. Errors: 400 when a name is empty, 409 when the batch would exceed the custom-attribute limit; nothing is added in that case.



# Edit Brand Perception Attribute Clusters
Source: https://docs.peec.ai/api-reference/brand-perception/edit-brand-perception-attribute-clusters

https://api.peec.ai/customer/v1/openapi/json post /brand-perception/attribute-clusters/edit
Rename and delete the project's brand-perception attributes, move terms between attributes and unassign terms from theirs — the same edits the Manage attributes screen makes. The whole call is one transaction: if any edit is rejected nothing is applied. Edits apply in the order reassign, rename, unassign_terms, delete_cluster_ids regardless of how they are listed. Neither deleting an attribute nor unassign_terms permanently removes a term — both unassign it, so it stays visible under `unassigned` and can be moved into an attribute later. Scores re-aggregate on the next read, so no new scraping run is needed. Naming one term or attribute twice in a call is rejected, since the two edits would race. To add an attribute, use the create endpoint. Errors: 400 when a target is repeated, 404 when an attribute or term does not exist, 409 when a new name collides with another attribute.



# Get Brand Perception Attribute History
Source: https://docs.peec.ai/api-reference/brand-perception/get-brand-perception-attribute-history

https://api.peec.ai/customer/v1/openapi/json get /brand-perception/attribute-history
How one brand's prominence on each brand-perception attribute has moved over time: one series per attribute, each point a day and the brand's average prominence (0-100) across that day's AI answers about the attribute. These are the same scores as the competitive breakdown, split by day instead of aggregated. The brand defaults to the project's own brand. The data covers the brand-perception runs of one industry and one target market. Pass `industry` to pick the industry; omitted, it is the one with the most recent completed run. The target market is always the industry's most recently completed one and cannot be picked. Both are returned as `industry` and `target_market`. Pagination applies to attributes.



# Get Brand Perception Attribute Rankings
Source: https://docs.peec.ai/api-reference/brand-perception/get-brand-perception-attribute-rankings

https://api.peec.ai/customer/v1/openapi/json get /brand-perception/attribute-rankings
How the project's own brand ranks against competitors for each brand-perception attribute. The ranking is the own brand's mean position across AI answers mentioning the attribute (lower is better). The data is aggregated across the brand-perception runs of one industry and one target market — there is no date range. Pass `industry` to pick the industry; omitted, it is the one with the most recent completed run. The target market is always the industry's most recently completed one and cannot be picked. Both are returned as `industry` and `target_market`.



# Get Brand Perception Attribute Sources
Source: https://docs.peec.ai/api-reference/brand-perception/get-brand-perception-attribute-sources

https://api.peec.ai/customer/v1/openapi/json get /brand-perception/attribute-sources
The sources feeding one attribute's associations: the URLs AI answers cited when describing the brand with this attribute. Data is aggregated across all brand-perception runs (no date range), and unlike the attribute rankings it is not scoped to one industry. An unknown attribute returns an empty result.



# Get Brand Perception Attributes
Source: https://docs.peec.ai/api-reference/brand-perception/get-brand-perception-attributes

https://api.peec.ai/customer/v1/openapi/json get /brand-perception/brand-attributes
How AI models describe the project's own brand: attribute clusters (e.g. "Luxury", "Racing Heritage") scored by average prominence per AI answer (0-100). The data is a snapshot of the latest brand-perception run — there is no date range. An empty result means the first run has not completed yet.



# Get Brand Perception Claim Sources
Source: https://docs.peec.ai/api-reference/brand-perception/get-brand-perception-claim-sources

https://api.peec.ai/customer/v1/openapi/json get /brand-perception/claim-sources
The pages behind one fact-checked claim, each with the strongest role it earned. Data is aggregated across every answer that made the claim and has no date range. Strongest tier first.



# Get Brand Perception Competitive Breakdown
Source: https://docs.peec.ai/api-reference/brand-perception/get-brand-perception-competitive-breakdown

https://api.peec.ai/customer/v1/openapi/json get /brand-perception/competitive-breakdown
The full competitive breakdown matrix: for every brand-perception attribute, the average prominence (0-100) of each brand — the project's own brand and its competitors — across AI answers. A higher score means the brand tends to be mentioned earlier when AI talks about that attribute. The data is aggregated across the brand-perception runs of one industry and one target market — there is no date range. Pass `industry` to pick the industry; omitted, it is the one with the most recent completed run. The target market is always the industry's most recently completed one and cannot be picked. Both are returned as `industry` and `target_market`. Pagination applies to attributes.



# Get Brand Perception Fact-Checking Verdicts
Source: https://docs.peec.ai/api-reference/brand-perception/get-brand-perception-fact-checking-verdicts

https://api.peec.ai/customer/v1/openapi/json get /brand-perception/fact-checking-verdicts
Claims AI models make about the project's brand, each judged against one of the project's facts as supported or contradicted. Data is aggregated across all fact-checked chats and has no date range. Newest claims first.



# Get Brand Perception Objection Sources
Source: https://docs.peec.ai/api-reference/brand-perception/get-brand-perception-objection-sources

https://api.peec.ai/customer/v1/openapi/json get /brand-perception/objection-sources
The sources AI models retrieved when asked about one objection. Data is aggregated across all objection runs and has no date range. An unknown objection returns an empty result.



# Get Brand Perception Objections
Source: https://docs.peec.ai/api-reference/brand-perception/get-brand-perception-objections

https://api.peec.ai/customer/v1/openapi/json get /brand-perception/objections
The recurring arguments AI models make against the project's brand when a buyer is deciding. Data is aggregated across all objection runs and has no date range.



# List Brand Perception Attribute Clusters
Source: https://docs.peec.ai/api-reference/brand-perception/list-brand-perception-attribute-clusters

https://api.peec.ai/customer/v1/openapi/json get /brand-perception/attribute-clusters
The project's brand-perception attribute taxonomy: every attribute with its id, name and terms (the raw phrasings from AI answers grouped under it), plus the unassigned terms no attribute claims. Unlike the brand-attributes endpoint this is the editable grouping rather than the scored snapshot, so it also lists attributes that carry no score yet. Use it to resolve the `cluster_id` values the edit endpoint takes and the create endpoint returns.



# List Brand Perception Industries
Source: https://docs.peec.ai/api-reference/brand-perception/list-brand-perception-industries

https://api.peec.ai/customer/v1/openapi/json get /brand-perception/industries
The industries the project has brand-perception runs for. Each run is dispatched for one industry, so a project that changed its industry has data for several — pass a `name` from here as the `industry` filter on the attribute-rankings and competitive-breakdown endpoints to read one of them. An empty result means no run has been dispatched yet.



# Create Project
Source: https://docs.peec.ai/api-reference/company/create-project

https://api.peec.ai/customer/v1/openapi/json post /projects
Create a project in the company, under the same plan limits and credit pool as creating it in the app. Add brands and prompts to it afterwards.



# List Projects
Source: https://docs.peec.ai/api-reference/company/list-projects

https://api.peec.ai/customer/v1/openapi/json get /projects
List the projects of a company



# Create Categories
Source: https://docs.peec.ai/api-reference/products/create-categories

https://api.peec.ai/customer/v1/openapi/json post /categories/create
Create product categories. Each item takes a `name` and an optional `parent_id` (omit or null for a top-level category). Items apply in order. Returns per-item results { created, rejected } — the batch never fails as a whole. Rejection reasons: parent_not_found, name_conflict (a sibling already has that name).



# Create Global Brand
Source: https://docs.peec.ai/api-reference/products/create-global-brand

https://api.peec.ai/customer/v1/openapi/json post /global-brands
Create a brand and return its `id` — pass it as a product's `global_brand_id` when creating products. The returned `name` is the brand's canonical name and may differ slightly from the name you sent. This is separate from `POST /brands`, which creates a brand a project tracks for AI-visibility reporting.



# Create Products
Source: https://docs.peec.ai/api-reference/products/create-products

https://api.peec.ai/customer/v1/openapi/json post /products/create
Create products. Each item is independent: valid products are created and per-item failures are returned in `rejected`, so the batch never fails as a whole. Optional `category_ids` assigns the product to categories.



# Delete Categories
Source: https://docs.peec.ai/api-reference/products/delete-categories

https://api.peec.ai/customer/v1/openapi/json post /categories/delete
Delete categories by id. Each one's child categories and products move up to its parent, then it is removed. Returns per-item results { deleted, rejected } — the batch never fails as a whole. Rejection reasons: not_found, name_conflict (a child moving up would clash with an existing sibling name).



# Delete Products
Source: https://docs.peec.ai/api-reference/products/delete-products

https://api.peec.ai/customer/v1/openapi/json post /products/delete
Delete products. Ids that don't exist in the project are returned in `skipped`.



# Get Product
Source: https://docs.peec.ai/api-reference/products/get-product

https://api.peec.ai/customer/v1/openapi/json post /products/detail
Get one product's detail over a date range: headline metrics (visibility, win_rate, avg_position, avg_rating, mention_count) plus a delta for each against the immediately preceding equal-length period, the catalog metadata (brand, description, image, source, first-seen date), the effective price range with any overrides, and the median AI-mention price. Visibility is divided by the product's relevant-prompt chats, not all shopping chats. avg_rating is the mean 0–5 star rating across the product's AI mentions (null when none carried a rating). Returns data: null when the product is not in the project.



# Get Shopping Attributes
Source: https://docs.peec.ai/api-reference/products/get-shopping-attributes

https://api.peec.ai/customer/v1/openapi/json post /products/attributes
The LLM-extracted attribute comparison grid for a product (scope=product) or the whole catalog (scope=overview), split by tab into characteristics, facts, and dimensions. Columns are competing brands (compare_by=brand) or competing products (compare_by=product, scope=product only). Deltas are computed against an explicit comparison window (previous_start_date/previous_end_date) or the equal-length window immediately before.



# Get Shopping Summary
Source: https://docs.peec.ai/api-reference/products/get-shopping-summary

https://api.peec.ai/customer/v1/openapi/json post /products/summary
Return aggregate shopping metrics over a date range. Delta fields compare against an explicit previous window or the auto-derived previous period.



# Get Shopping Trend
Source: https://docs.peec.ai/api-reference/products/get-shopping-trend

https://api.peec.ai/customer/v1/openapi/json post /products/trend
Return a product or brand shopping time series over a date range. Requires bucket and exactly one of product_ids or brand_ids.



# List Categories
Source: https://docs.peec.ai/api-reference/products/list-categories

https://api.peec.ai/customer/v1/openapi/json get /categories
List a project's product categories. Each row carries its full `path` and its `parent_id`, so the flat list reconstructs the category tree. Use the returned `id` as a `category_id` when creating, updating, or assigning products.



# List Global Brands
Source: https://docs.peec.ai/api-reference/products/list-global-brands

https://api.peec.ai/customer/v1/openapi/json get /global-brands
Search Peec's global brand catalog — the shared registry of real-world brands that products attach to via `global_brand_id`. Use it to find the `global_brand_id` for a brand when creating products. This is separate from `GET /brands`, which lists the brands a project tracks for AI-visibility reporting; the two use different ids. Primarily used with `search`. Pass `ownership` (`own`, `competitor`, or `all`) instead to list the project's shopping brands ranked by mentions, for use as shopping brand filters.



# List Merchants
Source: https://docs.peec.ai/api-reference/products/list-merchants

https://api.peec.ai/customer/v1/openapi/json post /products/merchants
List the merchants (sellers) whose product offers surfaced in AI answers, ranked over a date range: mentions, share of voice against the other merchants, buy-box win rate, average position, and average star rating, each with a delta against the previous window. Scope the population with category_ids or product_ids to get per-category or per-product seller breakdowns.



# List Products
Source: https://docs.peec.ai/api-reference/products/list-products

https://api.peec.ai/customer/v1/openapi/json post /products/list
List a project's products with headline metrics (mention_count, win_count, avg_position, avg_rating, visibility, share_of_voice) over the date range, filterable by category, merchant, brand, country, model channel, topic, and tag. Paginated.



# List Shopping Demand
Source: https://docs.peec.ai/api-reference/products/list-shopping-demand

https://api.peec.ai/customer/v1/openapi/json post /products/demand
List top shopping queries, web-search fan-out queries, or query terms over a date range.



# List Shopping Performance
Source: https://docs.peec.ai/api-reference/products/list-shopping-performance

https://api.peec.ai/customer/v1/openapi/json post /products/performance
List ranked product or category shopping performance over a date range.



# Update Categories
Source: https://docs.peec.ai/api-reference/products/update-categories

https://api.peec.ai/customer/v1/openapi/json post /categories/update
Rename and/or reparent categories by id. Each item sets `name` (rename), `parent_id` (move; null = promote to top level), or both — at least one is required. A combined edit is applied move-then-rename. Returns per-item results { updated, rejected } — the batch never fails as a whole. Rejection reasons: not_found, name_conflict, invalid_move (would nest a category inside itself).



# Update Products
Source: https://docs.peec.ai/api-reference/products/update-products

https://api.peec.ai/customer/v1/openapi/json post /products/update
Update products (name, description, image, price overrides, categories). Each item is independent: items with nothing to apply (not found, no changes, duplicate id) are reported in `skipped`, and unsatisfiable changes (name conflict, unknown category) in `rejected`, so the batch never fails as a whole.



# Accept Brand Suggestion
Source: https://docs.peec.ai/api-reference/project/accept-brand-suggestion

https://api.peec.ai/customer/v1/openapi/json post /brands/suggestions/{brand_suggestion_id}/accept
Accept a brand suggestion by ID, converting it into a brand within the project



# Accept Prompt Suggestion
Source: https://docs.peec.ai/api-reference/project/accept-prompt-suggestion

https://api.peec.ai/customer/v1/openapi/json post /prompts/suggestions/{prompt_suggestion_id}/accept
Accept a prompt suggestion by ID, creating a new prompt from it. Accepts both standard suggestions (`ps_`) and Prompt discovery suggestions (`pr_`); accepting a Prompt discovery suggestion also promotes its pending topic into a project topic. Optionally pass a country_code to override the suggestion's country for the created prompt — it applies to standard suggestions only, since a Prompt discovery suggestion keeps the market it was generated for.



# Accept Topic Suggestion
Source: https://docs.peec.ai/api-reference/project/accept-topic-suggestion

https://api.peec.ai/customer/v1/openapi/json post /topics/suggestions/{topic_suggestion_id}/accept
Accept a topic suggestion by ID, converting it into a regular topic



# Archive Prompt
Source: https://docs.peec.ai/api-reference/project/archive-prompt

https://api.peec.ai/customer/v1/openapi/json post /prompts/{prompt_id}/archive
Archive a prompt (is_archived = true) so it stops running while keeping its chats and history



# Create Brand
Source: https://docs.peec.ai/api-reference/project/create-brand

https://api.peec.ai/customer/v1/openapi/json post /brands
Create a new brand within a project



# Create Custom Domain Classification
Source: https://docs.peec.ai/api-reference/project/create-custom-domain-classification

https://api.peec.ai/customer/v1/openapi/json post /classifications/domains
Define a new custom domain classification for a project. Once created, it can be assigned to domains via the assignment endpoint.



# Create Custom URL Classification
Source: https://docs.peec.ai/api-reference/project/create-custom-url-classification

https://api.peec.ai/customer/v1/openapi/json post /classifications/urls
Define a new custom URL classification for a project. Once created, it can be assigned to URLs via the assignment endpoint.



# Create Prompt
Source: https://docs.peec.ai/api-reference/project/create-prompt

https://api.peec.ai/customer/v1/openapi/json post /prompts
Create a new prompt within a project. Without a `country_code` the prompt takes the market of its topic, or the project's market when the topic has none.



# Create Tag
Source: https://docs.peec.ai/api-reference/project/create-tag

https://api.peec.ai/customer/v1/openapi/json post /tags
Create a new tag within a project



# Create Topic
Source: https://docs.peec.ai/api-reference/project/create-topic

https://api.peec.ai/customer/v1/openapi/json post /topics
Create a new topic within a project



# Delete Brand
Source: https://docs.peec.ai/api-reference/project/delete-brand

https://api.peec.ai/customer/v1/openapi/json delete /brands/{brand_id}
Delete a brand within a project.



# Delete Custom Domain Classification
Source: https://docs.peec.ai/api-reference/project/delete-custom-domain-classification

https://api.peec.ai/customer/v1/openapi/json delete /classifications/domains
Delete a custom domain classification. Cascades through the override table, so any domains currently assigned this classification fall back to their heuristic classification.



# Delete Custom URL Classification
Source: https://docs.peec.ai/api-reference/project/delete-custom-url-classification

https://api.peec.ai/customer/v1/openapi/json delete /classifications/urls
Delete a custom URL classification. Cascades through the override table, so any URLs currently assigned this classification fall back to their heuristic classification.



# Delete Prompt
Source: https://docs.peec.ai/api-reference/project/delete-prompt

https://api.peec.ai/customer/v1/openapi/json delete /prompts/{prompt_id}
Delete a prompt and cascade to related chats



# Delete Tag
Source: https://docs.peec.ai/api-reference/project/delete-tag

https://api.peec.ai/customer/v1/openapi/json delete /tags/{tag_id}
Delete a tag within a project



# Delete Tag Group
Source: https://docs.peec.ai/api-reference/project/delete-tag-group

https://api.peec.ai/customer/v1/openapi/json delete /tag-groups
Delete a user-defined tag group. By default the tags are kept and simply ungrouped (their `group` becomes null); pass delete_tags=true to delete the tags themselves and detach them from every prompt. System groups (branding/intentType) cannot be deleted.



# Delete Topic
Source: https://docs.peec.ai/api-reference/project/delete-topic

https://api.peec.ai/customer/v1/openapi/json delete /topics/{topic_id}
Delete a topic, detaching all associated prompts and deleting prompt suggestions



# Generate Prompt Suggestions
Source: https://docs.peec.ai/api-reference/project/generate-prompt-suggestions

https://api.peec.ai/customer/v1/openapi/json post /prompts/suggestions/generate
Generate Prompt Builder suggestions for a project, the same way the Prompt Builder does. Generation runs in the background: this returns its generation ID as soon as it is queued. Poll `GET /prompts/suggestions/generations/{generation_id}` until it succeeds or fails, then list successful results with `GET /prompts/suggestions?legacy=false`. `topic_id`, `prompt_suggestion_id` and `segment` each narrow the run and are mutually exclusive; with an empty body every topic awaiting review is generated for again, replacing its current suggestions. The project's branding/intent split has to be configured first, with `PUT /project-profile` — generation has nothing to run against without it. Markets are optional: without them the project's own country and language are used.



# Generate Topics
Source: https://docs.peec.ai/api-reference/project/generate-topics

https://api.peec.ai/customer/v1/openapi/json post /topics/generate
Compose candidate topics for the project from its brand profile. Nothing is saved — review the returned names and create the ones you want with `POST /topics`. Composition already accounts for the project's existing topics, so it proposes only what fills a gap and can return an empty list when the set is already well covered. Rate limited per project; the `x-ratelimit-*` response headers report the remaining budget.



# Get Agent Visits
Source: https://docs.peec.ai/api-reference/project/get-agent-visits

https://api.peec.ai/customer/v1/openapi/json get /agent-analytics/visits
Aggregate agent access log visits grouped by a chosen dimension (bot, response status, host, path).



# Get Chat
Source: https://docs.peec.ai/api-reference/project/get-chat

https://api.peec.ai/customer/v1/openapi/json get /chats/{chat_id}/content
Get a single chat



# Get Project Profile
Source: https://docs.peec.ai/api-reference/project/get-project-profile

https://api.peec.ai/customer/v1/openapi/json get /project-profile
Read the project's brand profile (description, industry, brand identity, target markets, audience distribution, products & services). Returns `{ profile: null }` if the project hasn't been profiled yet.



# Get Prompt Suggestion Generation
Source: https://docs.peec.ai/api-reference/project/get-prompt-suggestion-generation

https://api.peec.ai/customer/v1/openapi/json get /prompts/suggestions/generations/{generation_id}
Get the authoritative state of a Prompt Builder suggestion generation queued by this project.



# Invite Project Members
Source: https://docs.peec.ai/api-reference/project/invite-project-members

https://api.peec.ai/customer/v1/openapi/json post /members/invite
Invite people to the project by email, as a viewer or an owner. Each person gets the same invitation email as an invite from the app. An email that already has a Peec account gets access right away; anyone else gets access once they sign up from the email. An email that already has access or an open invitation lands in `skipped`, and the request never fails as a whole because of one item. Returns 403 when the company has turned off email invitations.



# List Agent logs
Source: https://docs.peec.ai/api-reference/project/list-agent-logs

https://api.peec.ai/customer/v1/openapi/json get /agent-analytics/logs
List Agent access logs from your log provider integration or access file upload



# List Bots
Source: https://docs.peec.ai/api-reference/project/list-bots

https://api.peec.ai/customer/v1/openapi/json get /agent-analytics/bots
List all known AI agent bots from agent analytics.



# List Brand Social Channels
Source: https://docs.peec.ai/api-reference/project/list-brand-social-channels

https://api.peec.ai/customer/v1/openapi/json get /brands/social-channels
List the social channels configured for a project, optionally filtered to one brand.



# List Brand Suggestions
Source: https://docs.peec.ai/api-reference/project/list-brand-suggestions

https://api.peec.ai/customer/v1/openapi/json get /brands/suggestions
List the open brand suggestions of a project



# List Brands
Source: https://docs.peec.ai/api-reference/project/list-brands

https://api.peec.ai/customer/v1/openapi/json get /brands
List the brands of a project



# List Chats
Source: https://docs.peec.ai/api-reference/project/list-chats

https://api.peec.ai/customer/v1/openapi/json get /chats
List the chats of a project



# List Custom Domain Classifications
Source: https://docs.peec.ai/api-reference/project/list-custom-domain-classifications

https://api.peec.ai/customer/v1/openapi/json get /classifications/domains
List the custom domain classifications defined for a project. These complement the built-in classifications and can be assigned to domains.



# List Custom URL Classifications
Source: https://docs.peec.ai/api-reference/project/list-custom-url-classifications

https://api.peec.ai/customer/v1/openapi/json get /classifications/urls
List the custom URL classifications defined for a project. These complement the built-in classifications and can be assigned to URLs.



# List Fanout Search Queries
Source: https://docs.peec.ai/api-reference/project/list-fanout-search-queries

https://api.peec.ai/customer/v1/openapi/json post /queries/search
List the fanout search queries of a project



# List Fanout Shopping Queries
Source: https://docs.peec.ai/api-reference/project/list-fanout-shopping-queries

https://api.peec.ai/customer/v1/openapi/json post /queries/shopping
List the fanout shopping queries of a project



# List Model Channels
Source: https://docs.peec.ai/api-reference/project/list-model-channels

https://api.peec.ai/customer/v1/openapi/json get /model-channels
List the model channels



# List Models
Source: https://docs.peec.ai/api-reference/project/list-models

https://api.peec.ai/customer/v1/openapi/json get /models
Deprecated: use List Model Channels instead.



# List Prompt Suggestions
Source: https://docs.peec.ai/api-reference/project/list-prompt-suggestions

https://api.peec.ai/customer/v1/openapi/json get /prompts/suggestions
List the prompt suggestions of a project



# List Prompts
Source: https://docs.peec.ai/api-reference/project/list-prompts

https://api.peec.ai/customer/v1/openapi/json get /prompts
List the prompts of a project



# List Tag Groups
Source: https://docs.peec.ai/api-reference/project/list-tag-groups

https://api.peec.ai/customer/v1/openapi/json get /tag-groups
List the user-defined tag groups of a project (distinct non-empty `group` values across the project's tags), each with its shared color and tag count. System groups (branding/intentType) are not included — see List Tags for those.



# List Tags
Source: https://docs.peec.ai/api-reference/project/list-tags

https://api.peec.ai/customer/v1/openapi/json get /tags
List the tags of a project. Tags include user-created tags and Peec-managed system tags (is_system=true). Each tag carries a `group`: for system tags this is the mutually-exclusive dimension (branding or intentType); for user tags it is the user-defined group name (or null). Pass `group` to filter to a single user-defined group. System tags cannot be edited or deleted.



# List Topic Suggestions
Source: https://docs.peec.ai/api-reference/project/list-topic-suggestions

https://api.peec.ai/customer/v1/openapi/json get /topics/suggestions
List the topic suggestions of a project



# List Topics
Source: https://docs.peec.ai/api-reference/project/list-topics

https://api.peec.ai/customer/v1/openapi/json get /topics
List the topics of a project



# Reject Brand Suggestion
Source: https://docs.peec.ai/api-reference/project/reject-brand-suggestion

https://api.peec.ai/customer/v1/openapi/json post /brands/suggestions/{brand_suggestion_id}/reject
Reject a brand suggestion by ID, removing it from the project and preventing it from being re-suggested



# Reject Prompt Suggestion
Source: https://docs.peec.ai/api-reference/project/reject-prompt-suggestion

https://api.peec.ai/customer/v1/openapi/json post /prompts/suggestions/{prompt_suggestion_id}/reject
Reject a prompt suggestion by ID, deleting it. Accepts both standard suggestions (`ps_`) and Prompt discovery suggestions (`pr_`).



# Reject Topic Suggestion
Source: https://docs.peec.ai/api-reference/project/reject-topic-suggestion

https://api.peec.ai/customer/v1/openapi/json post /topics/suggestions/{topic_suggestion_id}/reject
Reject a topic suggestion by ID, deleting it and its associated prompt suggestions



# Set Brand Social Channels
Source: https://docs.peec.ai/api-reference/project/set-brand-social-channels

https://api.peec.ai/customer/v1/openapi/json put /brands/{brand_id}/social-channels
Replace the complete list of social channels configured for a brand. Pass an empty list to remove them all.



# Set Domain Classification
Source: https://docs.peec.ai/api-reference/project/set-domain-classification

https://api.peec.ai/customer/v1/openapi/json put /classifications/domain-assignments
Assign a built-in or custom classification to a domain (overriding any heuristic classification), or clear the assignment by passing null.



# Set Project Profile
Source: https://docs.peec.ai/api-reference/project/set-project-profile

https://api.peec.ai/customer/v1/openapi/json put /project-profile
Replace the project's brand profile. All fields are required — the entire profile is overwritten. Triggers a background refresh of prompt suggestions. Audience distribution percentages must sum to 100. The project's display name is not part of the profile and cannot be changed via this endpoint. Returns 403 while the project is in onboarding.



# Set URL Classification
Source: https://docs.peec.ai/api-reference/project/set-url-classification

https://api.peec.ai/customer/v1/openapi/json put /classifications/url-assignments
Assign a built-in or custom classification to a URL (overriding any heuristic classification), or clear the assignment by passing null.



# Unarchive Prompt
Source: https://docs.peec.ai/api-reference/project/unarchive-prompt

https://api.peec.ai/customer/v1/openapi/json post /prompts/{prompt_id}/unarchive
Unarchive a prompt (is_archived = false), reactivating it. Subject to the project's active-prompt plan limit



# Update Brand
Source: https://docs.peec.ai/api-reference/project/update-brand

https://api.peec.ai/customer/v1/openapi/json patch /brands/{brand_id}
Update a brand within a project. Changes to name, regex, or aliases trigger a background recalculation of metrics. While recalculation is in progress, further updates to these fields are blocked (409 Conflict) until it completes.



# Update Prompt
Source: https://docs.peec.ai/api-reference/project/update-prompt

https://api.peec.ai/customer/v1/openapi/json patch /prompts/{prompt_id}
Update a prompt's topic and tags within a project



# Update Prompt Suggestions
Source: https://docs.peec.ai/api-reference/project/update-prompt-suggestions

https://api.peec.ai/customer/v1/openapi/json post /prompts/suggestions/update
Edit pending Prompt discovery suggestions (`pr_`) before accepting them: rewrite the text and/or replace the tag set per item. Editing keeps a suggestion pending — accept it to create the tracked prompt. Each item is independent: unknown ids are reported in `skipped`, and unsatisfiable items (a standard `ps_` suggestion, an unknown tag, a duplicate id, nothing to change) in `rejected`, so the batch never fails as a whole.



# Update Tag
Source: https://docs.peec.ai/api-reference/project/update-tag

https://api.peec.ai/customer/v1/openapi/json patch /tags/{tag_id}
Update a tag within a project



# Update Tag Group
Source: https://docs.peec.ai/api-reference/project/update-tag-group

https://api.peec.ai/customer/v1/openapi/json patch /tag-groups/{group}
Rename and/or recolor a user-defined tag group. Applies to every tag in the group. System groups (branding/intentType) cannot be modified.



# Update Topic
Source: https://docs.peec.ai/api-reference/project/update-topic

https://api.peec.ai/customer/v1/openapi/json patch /topics/{topic_id}
Update a topic within a project



# Get Brands Report
Source: https://docs.peec.ai/api-reference/reports/get-brands-report

https://api.peec.ai/customer/v1/openapi/json post /reports/brands
Get a report on Brands.

## Prompt Scope

The report covers the project's active prompts. An archived prompt is counted only when `filters` selects it with a `prompt_id` `in` predicate; a `not_in` filter or a `having` predicate does not bring it back.

## Aggregation Formulas

When aggregating results across multiple rows/dimensions, use the following formulas:

- **sentiment**: `((sum(sentiment_sum) / sum(sentiment_count)) / 2 + 0.5) * 100`
- **position**: `sum(position_sum) / sum(position_count)`
- **visibility**: `sum(visibility_count) / sum(visibility_total)`
- **share_of_voice**: `mention_count / sum(mention_count)`
- **win_rate**: `sum(win_count) / sum(visibility_total)`

## `filters` vs `having`

`filters` are **pre-aggregation** row filters (applied as WHERE before GROUP BY). They shrink both the numerator and the denominator of ratio metrics. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `brand_id`. Note that `brand_id` in `filters` shrinks `share_of_voice`'s denominator too — so filtering to one brand collapses SoV to 1.0. Use `having` for `brand_id` if you want SoV preserved.

`having` are **post-aggregation** row filters (applied as HAVING after GROUP BY). They select which aggregated rows are returned and do **not** shrink ratio-metric denominators. Filtering `{field: "brand_id", values: [X]}` here returns only brand X's row, but `share_of_voice` still divides X's mentions by mentions across all in-scope brands — so SoV stays in [0, 1]. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `brand_id`.

Population fields (`model_id` etc.) are also allowed in `having` but require the matching value in `dimensions` so the column appears in GROUP BY; otherwise the request is rejected.

When `dimensions` are requested, the `share_of_voice` denominator follows the same grouping as the numerator. Requesting `prompt_id` as a dimension produces per-(brand × prompt) rows whose `share_of_voice` is the brand's mentions in that prompt divided by all brands' mentions in that prompt.



# Get Domains Report
Source: https://docs.peec.ai/api-reference/reports/get-domains-report

https://api.peec.ai/customer/v1/openapi/json post /reports/domains
Get a report on Source Domains.

## Prompt Scope

The report covers the project's active prompts. An archived prompt is counted only when `filters` selects it with a `prompt_id` `in` predicate; a `not_in` filter or a `having` predicate does not bring it back.

## Aggregation Formulas

When aggregating results across multiple rows/dimensions, use the following formulas:

- **citation_rate**: `sum(citation_count) / sum(retrieval_count)`
- **retrieval_rate**: `sum(retrieval_count) / sum(total_chat_count)`
- **retrieval_percentage**: `sum(retrieved_chat_count) / sum(total_chat_count)`
- **cited_percentage**: `sum(cited_chat_count) / sum(total_chat_count)`

## `filters` vs `having`

`filters` are **pre-aggregation** row filters (applied as WHERE before GROUP BY) on the source-row table. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `url`, `url_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap`.
- Population (`model_id`, `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`) shrink both numerator and denominator (`total_chat_count`).
- Source-side (`domain`, `domain_classification`, `url`, `url_classification`) and per-row mentioned-brand predicates (`mentioned_brand_id`, `mentioned_brand_count`, `gap`) shrink the source-row scope feeding aggregation. `total_chat_count` is computed from a chat-level table that doesn't carry these columns, so the denominator narrows only on chat-level fields.

`having` are **post-aggregation** row filters (applied as HAVING after GROUP BY). Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap`. They select which aggregated rows are returned and do not affect denominators.



# Get Links Report
Source: https://docs.peec.ai/api-reference/reports/get-links-report

https://api.peec.ai/customer/v1/openapi/json post /reports/links
Get a report on the domains AI answers linked to in their own text. A link is a URL the answer wrote into its prose; it is never one of the sources the answer retrieved or cited, which the domains report covers.

## Prompt Scope

The report covers the project's active prompts. An archived prompt is counted only when `filters` selects it with a `prompt_id` `in` predicate.

## Aggregation Formulas

When aggregating results across multiple rows/dimensions:

- **linked_percentage**: `sum(linked_chat_count) / sum(total_chat_count)`, only across rows that do not split the same chats (not across `url` rows of one domain).
- **average_link_position** is not additive across rows. Request the coarser breakdown instead.



# Get URL Content
Source: https://docs.peec.ai/api-reference/reports/get-url-content

https://api.peec.ai/customer/v1/openapi/json post /sources/urls/content
Return the scraped markdown content of a source URL. Use the URLs report to discover URLs.



# Get URLs Report
Source: https://docs.peec.ai/api-reference/reports/get-urls-report

https://api.peec.ai/customer/v1/openapi/json post /reports/urls
Get a report on Source URLs.

## Prompt Scope

The report covers the project's active prompts. An archived prompt is counted only when `filters` selects it with a `prompt_id` `in` predicate; a `not_in` filter or a `having` predicate does not bring it back.

## Aggregation Formulas

When aggregating results across multiple rows/dimensions, use the following formula:

- **citation_rate**: `sum(citation_count) / sum(retrieval_count)`
- **citation_position**: `sum(citation_position_sum) / sum(citation_position_count)`

## `filters` vs `having`

`filters` are **pre-aggregation** row filters (applied as WHERE before GROUP BY) on the source-row table. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `url`, `url_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap`.
- Population (`model_id`, `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`) shrink both numerator and denominator scope.
- Source-side (`domain`, `domain_classification`, `url`, `url_classification`) and per-row mentioned-brand predicates (`mentioned_brand_id`, `mentioned_brand_count`, `gap`) shrink the source-row scope feeding aggregation.

`having` are **post-aggregation** row filters (applied as HAVING after GROUP BY). Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `url`, `url_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap`.

`citation_rate` is computed per row from numerator (`citation_count`) and denominator (`retrieval_count`) inside the same aggregation group, so neither filter placement can collapse it. The shared fields exist in both `filters` and `having` — use `filters` to prune source rows before aggregation (typically more efficient), use `having` to operate on the aggregated `mentioned_brands` union for entity-wide selection.



# Authentication for Peec API
Source: https://docs.peec.ai/api/authentication



All requests to the **Peec AI Customer API** must be authenticated with a valid API key. API keys can be scoped at either the **company** or **project** level, depending on your use case. Create your API key [here](https://app.peec.ai/api-keys).

***

## Passing API Keys

You can authenticate by providing your API key in one of two ways:

### 1. HTTP Header

```bash theme={null}
curl -X GET "https://api.peec.ai/customer/v1/prompts" \
  -H "x-api-key: YOUR_API_KEY"
```

### 2. Query Parameter

```bash theme={null}
curl -X GET "https://api.peec.ai/customer/v1/prompts?api_key=YOUR_API_KEY"
```

> We recommend using the x-api-key header for better security.

## API key scopes

API key scopes determine the level of access granted to the API. Choosing the appropriate scope helps ensure that your integrations have only the permissions they need.

* **Company-scoped keys**: Provide access across all projects within your organization. Use when building integrations that span multiple projects.
* **Project-scoped keys:** Limited to a single project. Use when you need to isolate access for specific applications, environments, or teams.

## Best practices

* Keep your API keys secret and never expose them in client-side code.
* Rotate keys regularly.
* Use project-scoped keys where possible to limit risk.


# Changelog
Source: https://docs.peec.ai/api/changelog

Track updates, improvements, and breaking changes to the Peec API.

## How to read this changelog

This changelog documents all updates, improvements, and fixes to the Peec Customer API.

<Warning>
  The API is currently in v0 (beta). During this phase, features and endpoints are subject to change, and breaking changes may occur. Once the API reaches v1, breaking changes will be minimized.
</Warning>

### Changelog Categories

* **Breaking Changes:** API changes that may require updates to your integration.
* **Added:** New features or capabilities.
* **Changed:** Updates to existing functionality that aren’t breaking.
* **Deprecated:** Features still available but planned for removal.
* **Removed:** Features removed from the API.
* **Fixed:** Bug fixes and corrections.
* **Security:** Updates addressing vulnerabilities or improving security.

# Changelog

<Update label="September 28, 2026" description="v0.37.0">
  ### Added

  * **Create Project endpoint** New [Create Project](/api-reference/company/create-project) endpoint creates a project in your company under the same plan limits, project limit, and credit pool as creating one in the app. Call it with a company API key. `name`, `domain`, and `country_code` are required. Pass `allocated_credits` for every project except your company's first project before it has a plan, and except a pitch project, which takes none. Agency and partner companies can create a pitch project with `is_pitch`, and an instant pitch with `is_instant_pitch` alongside it. The response returns the new project's `id`, which you then pass as `project_id` to add brands and prompts. Returns `400` when a required value is missing or a plan limit is reached, `403` for a key that isn't a company key, and `429` when `allocated_credits` exceeds your unallocated credits or the rate limit is hit.
</Update>

<Update label="September 28, 2026" description="v0.36.0">
  ### Added

  * **Actions endpoints** New [Actions](/api-reference/actions/list-actions) endpoints for reading the actions Peec generates for a project, writing your own, and tracking their status and step completion.
</Update>

<Update label="September 27, 2026" description="v0.35.0">
  ### Added

  * **Content optimization actions** On projects with **Content optimization** enabled, List Actions and Get Action now return `CONTENT_OPTIMISATION` actions, which improve an existing page you own. Use `types: ["CONTENT_OPTIMISATION"]` to filter for these actions, and add this value to clients that enumerate action types. Update Action Status, Update Actions, and Set Action Step Completion accept these actions on the same projects. On other projects, their IDs are returned in `skipped`.
  * **Optimize content endpoints** Three new endpoints for working with the article behind a `CONTENT_OPTIMISATION` action. Each takes a `project_id` and an `action_id`, and returns `403` when Content optimization isn't enabled for the project.
    * `POST /customer/v1/actions/optimize_content` returns the article as plain text, the page URL, the optimization score out of 100, and its `suggestions`. Each suggestion has an `id`, `category`, `text`, `state` (`pending`, `accepted`, or `rejected`), and `kind`. A `rewrite` carries wording to accept or dismiss. An `edit` only names what's missing.
    * `POST /customer/v1/actions/optimize_content/edit` rewrites up to 50 passages in one revision. Each edit quotes a whole paragraph or heading as `original_text` and gives its markdown replacement as `new_text`. An optional `carries_out_suggestion_id` marks an `edit` suggestion accepted. Nothing is written unless every edit applies, and a failed edit returns `400`. Returns the new `score`, the counts `edited` and `carried_out`, and `suggestion_ids`.
    * `POST /customer/v1/actions/optimize_content/suggestions/resolve` applies `accept`, `reject`, or `revert` to up to 50 `suggestion_ids` in one revision. IDs already in the requested state are counted in `unchanged`. An unknown ID, or reverting an edit you typed yourself, returns `400`. Returns the new `score`, `unchanged`, and each suggestion's resulting `state`.
    * Both write endpoints need an API key with write access, and return `409` if the article changed while the request ran. Read it again and retry.
</Update>

<Update label="September 18, 2026" description="v0.34.0">
  ### Added

  * **Owned-source correction actions** [List Actions](/api-reference/actions/list-actions) and [Get Action](/api-reference/actions/get-action) now return `CONTRADICTIONS_OWNED_SOURCES` for corrections to one source page on an owned domain. Use `types: ["CONTRADICTIONS_OWNED_SOURCES"]` to filter for these actions, and add this value to clients that enumerate action types. `CONTRADICTIONS_EXTERNAL_SOURCES` remains the type for third-party source corrections. Source-correction actions include impacted prompts with measured owned-domain citation share. Response and expected-outcome fields are unchanged.
</Update>

<Update label="July 10, 2026" description="v0.33.0">
  ### Added

  * **Tag group management** Tags can now belong to a user-defined group, and tags in a group share a color.
    * [Create Tag](/api-reference/project/create-tag) and [Update Tag](/api-reference/project/update-tag) accept an optional `group` field. Setting a group moves the tag into it (inheriting the group's color, so `color` is ignored); passing `null` on Update Tag removes the tag from its group.
    * [List Tags](/api-reference/project/list-tags) now returns the user-defined `group` for user tags (previously only system tags carried a `group`) and accepts a `group` query parameter to filter by group.
    * New [List Tag Groups](/api-reference/project/list-tag-groups) endpoint returns each user-defined group with its shared color and tag count.
    * New [Update Tag Group](/api-reference/project/update-tag-group) endpoint renames and/or recolors every tag in a group.
    * New [Delete Tag Group](/api-reference/project/delete-tag-group) endpoint ungroups a group's tags by default, or deletes them with `delete_tags: true`.
</Update>

<Update label="June 27, 2026" description="v0.32.0">
  ### Added

  * **Archive and Unarchive Prompt endpoints** New [Archive Prompt](/api-reference/project/archive-prompt) and [Unarchive Prompt](/api-reference/project/unarchive-prompt) endpoints for pausing and resuming tracking of a prompt without deleting it. Archived prompts are excluded from [List Chats](/api-reference/project/list-chats) by default — pass `include_archived_prompts=true` to include their historical chats. Unarchiving is subject to your plan's active-prompt limit.
</Update>

<Update label="June 26, 2026" description="v0.31.0">
  ### Added

  * **`is_system` and `group` on List Tags** The [List Tags](/api-reference/project/list-tags) endpoint now returns `is_system` — whether the tag is a system tag maintained by Peec and auto-assigned to every prompt by its classification — and `group`, the system tag group the tag belongs to: `branding` (the branded / non-branded distinction) or `intentType` (the informational / commercial / transactional distinction). `group` is `null` for user-created tags.
</Update>

<Update label="June 25, 2026" description="v0.30.0">
  ### Added

  * **Products endpoints** A new group of Products endpoints exposes Peec's shopping data.
    * [List Products](/api-reference/products/list-products): a project's products with headline metrics (`mention_count`, `win_count`, `avg_position`, `visibility`, `share_of_voice`) over a date range, filterable by `product_ids`, `brand_ids`, `category_ids`, `merchant_ids`, `country_codes`, `model_channel_ids`, `topic_ids`, `tag_ids`, `source`, and `search`, with `order_by` (`visibility`, `win_rate`, `avg_position`, `mention_count`, `name`) and pagination.
    * [Get Product](/api-reference/products/get-product): detailed metrics for a single product over a date range, including period-over-period deltas, AI-quoted price ranges, and win rate.
    * [Create Products](/api-reference/products/create-products), [Update Products](/api-reference/products/update-products), and [Delete Products](/api-reference/products/delete-products): batch endpoints (up to 1,000 items per request) for managing products. Each returns per-item results, separating succeeded items from rejected ones with a reason.
    * [Get Shopping Attributes](/api-reference/products/get-shopping-attributes): a comparison grid of AI-extracted product attributes (`characteristics`, `facts`, `dimensions`) for a single product or the whole catalog, compared across brands or products.
  * **Category management endpoints** New [List Categories](/api-reference/products/list-categories), [Create Categories](/api-reference/products/create-categories), [Update Categories](/api-reference/products/update-categories), and [Delete Categories](/api-reference/products/delete-categories) endpoints for organizing products into a category tree. Create, update, and delete are batch endpoints returning per-item results with a rejection reason where applicable.
  * **List Global Brands endpoint** New [List Global Brands](/api-reference/products/list-global-brands) endpoint for searching Peec's global brand catalog by name or alias. Pass the optional `ownership` parameter (`own`, `competitor`, or `all`) to instead list the project's own shopping brands ranked by mention count; in that mode each result also includes `mention_count` and `is_own`.
  * **`chat_scope` on Product endpoints** [List Products](/api-reference/products/list-products) and [Get Product](/api-reference/products/get-product) accept an optional `chat_scope` parameter controlling the visibility denominator: `all` counts every in-scope chat, `shopping` counts only product-gallery chats. Defaults to `shopping`.
</Update>

<Update label="June 16, 2026" description="v0.29.0">
  ### Added

  * **`created_at` and creation-date filtering on Get Projects** The [Get Projects](/api-reference/company/get-projects) endpoint now returns a `created_at` field (RFC 3339 full-date, e.g. `2025-09-22`) for each project, and accepts optional `start_date` and `end_date` query parameters to filter projects by their creation date. Both bounds are inclusive and interpreted in UTC.
</Update>

<Update label="June 15, 2026" description="v0.28.0">
  ### Added

  * **snake\_case field-name corrections** A handful of response fields were inadvertently camelCase, inconsistent with the API's snake\_case convention. Their snake\_case equivalents have been added; the camelCase versions are now deprecated (see below). Existing integrations keep working until the camelCase fields are removed.
    * [Get Chat](/api-reference/project/get-chat): each source now includes `url_normalized`, `citation_count`, and `citation_position`; each ad includes `brand_name`, `ad_unit_type`, and `ads_request_id`; each ad card includes `image_url` and `target_url`.
    * **`total_count` on list endpoints** The [List Brands](/api-reference/project/list-brands), [List Chats](/api-reference/project/list-chats), [List Prompts](/api-reference/project/list-prompts), [List Tags](/api-reference/project/list-tags), [List Topics](/api-reference/project/list-topics), [List Fanout Search Queries](/api-reference/project/list-fanout-search-queries), and [List Fanout Shopping Queries](/api-reference/project/list-fanout-shopping-queries) endpoints now return a `total_count` field.
    * [Get Project Profile](/api-reference/project/get-project-profile): now returns `brand_presentation`, `products_and_services`, `target_markets` (each with `market_size` and `osm_id`), `audience_distribution` (with `simple_recommendation_seeker`, `informed_shopper`, and `evaluative_researcher`), and `used_prepared_profile`.

  ### Changed

  * **[Set Project Profile](/api-reference/project/set-project-profile) accepts snake\_case** The request body now also accepts snake\_case field names (`brand_presentation`, `products_and_services`, `target_markets[].market_size` / `osm_id`, `audience_distribution.simple_recommendation_seeker` / `informed_shopper` / `evaluative_researcher`), matching the rest of the API. The camelCase field names are still accepted for backward compatibility.

  ### Deprecated

  * **camelCase field names** The camelCase equivalents of the fields above are deprecated and will be removed in a future version. Migrate to snake\_case:
    * Get Chat sources: `urlNormalized` → `url_normalized`, `citationCount` → `citation_count`, `citationPosition` → `citation_position`.
    * Get Chat ads: `brandName` → `brand_name`, `adUnitType` → `ad_unit_type`, `adsRequestId` → `ads_request_id`, `imageUrl` → `image_url`, `targetUrl` → `target_url`.
    * List endpoints: `totalCount` → `total_count`.
    * Project Profile: `brandPresentation` → `brand_presentation`, `productsAndServices` → `products_and_services`, `targetMarkets` → `target_markets`, `marketSize` → `market_size`, `osmId` → `osm_id`, `audienceDistribution` → `audience_distribution`, `simpleRecommendationSeeker` → `simple_recommendation_seeker`, `informedShopper` → `informed_shopper`, `evaluativeResearcher` → `evaluative_researcher`, `usedPreparedProfile` → `used_prepared_profile`.
</Update>

<Update label="June 10, 2026" description="v0.27.0">
  ### Added

  * **`week` and `month` dimensions on Report Endpoints** The [Get Brands Report](/api-reference/reports/get-brands-report), [Get Domains Report](/api-reference/reports/get-domains-report), and [Get URLs Report](/api-reference/reports/get-urls-report) endpoints now accept `week` and `month` in the `dimensions` array, aggregating results into weekly or monthly time buckets instead of the daily breakdown provided by `date`. Results broken down by `week` include a `week` field containing the Monday that starts the ISO week; results broken down by `month` include a `month` field containing the first day of the month.
</Update>

<Update label="June 8, 2026" description="v0.26.0">
  ### Added

  * **`having` filter on Report Endpoints** The [Get Brands Report](/api-reference/reports/get-brands-report), [Get Domains Report](/api-reference/reports/get-domains-report), and [Get URLs Report](/api-reference/reports/get-urls-report) endpoints now accept an optional `having` array of post-aggregation filters that select which aggregated results are returned **without** shrinking the denominators of ratio metrics. Unlike `filters` (which apply before aggregation), `having` lets you narrow to a single brand, domain, or URL while metrics like `share_of_voice` stay measured against the full in-scope population. Population fields (`model_id`, `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`) used in `having` require the matching value in `dimensions`, otherwise the request is rejected. Multiple `having` filters are AND'd together. See [Filtering and dimensions](/api/filtering-and-dimensions) for guidance on when to use `filters` vs `having`.

  ### Fixed

  * **`share_of_voice` denominator now scoped per dimension** On the [Get Brands Report](/api-reference/reports/get-brands-report), `share_of_voice` is now computed against total mentions within each result's dimension grouping rather than a single project-wide total. When breaking down by `prompt_id` (or any other dimension), each brand's share is now its mentions in that grouping divided by all brands' mentions in the same grouping. Previously the same denominator was applied across every result, distorting share values in broken-down reports.
</Update>

<Update label="May 27, 2026" description="v0.25.2">
  ### Removed

  * **`IMAGE` removed from `features`** The `IMAGE` value is no longer part of the `features` array returned by the [List Chats](/api-reference/project/list-chats) and [Get Chat](/api-reference/project/get-chat) endpoints, and is no longer accepted by the [List Chats](/api-reference/project/list-chats) `features` filter. Remaining values: `SHOPPING`, `PRODUCT_COMPARISON`, `AD`, `MAP`, `WEB_SEARCH`.
</Update>

<Update label="May 22, 2026" description="v0.25.1">
  ### Changed

  * **List Chats excludes archived and deleted prompts by default** The [List Chats](/api-reference/project/list-chats) endpoint now excludes chats whose prompt has been archived or deleted. To include chats for archived prompts (e.g. historical lookback for a prompt that is no longer tracked), pass `include_archived_prompts=true`. Chats for deleted prompts are always excluded.

  ### Fixed

  * **`features` values on Get Chat** The [Get Chat](/api-reference/project/get-chat) endpoint now returns `features` using the same values accepted by the [List Chats](/api-reference/project/list-chats) `features` filter: `SHOPPING`, `PRODUCT_COMPARISON`, `IMAGE`, `AD`, `MAP`, `WEB_SEARCH`. Previously it returned internal element names (e.g. `PRODUCT_GALLERY`, `LOCAL_BUSINESS`, `SOURCES`), which could not be passed back as filters.
</Update>

<Update label="May 21, 2026" description="v0.25.0">
  ### Added

  * **List Bots Endpoint** New [List Bots](/api-reference/project/list-bots) endpoint returning every AI agent bot tracked by Peec Agent Analytics, with each bot's `id` (user agent), `provider`, and `type` (`training`, `search`, `userQuery`, `other`).
  * **Get Agent Visits Endpoint** New [Get Agent Visits](/api-reference/project/get-agent-visits) endpoint aggregating AI bot visit counts from connected access logs over a date range. Supports `group_by` across `bot_id`, `response_status`, `request_host`, and `request_path`, an optional `bot_ids` filter, and `time_bucket` (`hour`, `day`, `week`, `month`) for time-series breakdowns.
  * **`features` field on Chat Endpoints** The [List Chats](/api-reference/project/list-chats) and [Get Chat](/api-reference/project/get-chat) endpoints now return a `features` array — feature flags for special elements detected in the assistant response (shopping carousels, product comparisons, image galleries, ads, map widgets, web search).
  * **`features` filter on List Chats** The [List Chats](/api-reference/project/list-chats) endpoint now accepts an optional `features` array parameter. Values: `SHOPPING`, `PRODUCT_COMPARISON`, `IMAGE`, `AD`, `MAP`, `WEB_SEARCH`. Multiple values are AND'd — a chat must contain every listed feature to match.
  * **`maps` and `ads` fields on Get Chat** The [Get Chat](/api-reference/project/get-chat) endpoint now returns `maps` (local-business map cards with name and Google Maps directions URL) and `ads` (paid ad placements with brand, target URL, ad unit type, and card content).
</Update>

<Update label="April 28, 2026" description="v0.24.0">
  ### Added

  * **`domain_classification` filter for Domains and URLs reports** New filter on the [Get Domains Report](/api-reference/reports/get-domains-report) and [Get URLs Report](/api-reference/reports/get-urls-report) endpoints to narrow results by domain classification. Operators: `in`, `not_in`. Values: array of `CORPORATE`, `EDITORIAL`, `INSTITUTIONAL`, `OTHER`, `REFERENCE`, `UGC`, `COMPETITOR`, `OWN`.
  * **`url_classification` filter for URLs Report** New filter on the [Get URLs Report](/api-reference/reports/get-urls-report) endpoint to narrow results by URL classification. Operators: `in`, `not_in`. Values: array of `HOMEPAGE`, `CATEGORY_PAGE`, `PRODUCT_PAGE`, `LISTICLE`, `COMPARISON`, `PROFILE`, `ALTERNATIVE`, `DISCUSSION`, `HOW_TO_GUIDE`, `ARTICLE`, `OTHER`.
</Update>

<Update label="April 28, 2026" description="v0.23.1">
  ### Fixed

  * **`total_chat_count` Now Respects Filters on Domains Report** The [Get Domains Report](/api-reference/reports/get-domains-report) endpoint now applies request filters to `total_chat_count`, so the denominator used for `retrieval_rate` and `retrieved_percentage` reflects the filtered scope.
</Update>

<Update label="April 27, 2026" description="v0.23.0">
  ### Added

  * **Project Profile Endpoints** New [Get Project Profile](/api-reference/project/get-project-profile) and [Set Project Profile](/api-reference/project/set-project-profile) endpoints for retrieving and updating the profile of a project.
  * **`retrieved_chat_count` and `total_chat_count` on Domains Report** The [Get Domains Report](/api-reference/reports/get-domains-report) endpoint now returns `retrieved_chat_count` (distinct chats in which at least one URL from the domain was retrieved) and `total_chat_count` (total chats in scope for the result, used as the denominator for `retrieval_rate` and `retrieved_percentage`).
</Update>

<Update label="April 23, 2026" description="v0.22.0">
  ### Added

  * **`order_by` Parameter on Report Endpoints** The [Get Brands Report](/api-reference/reports/get-brands-report), [Get Domains Report](/api-reference/reports/get-domains-report), and [Get URLs Report](/api-reference/reports/get-urls-report) endpoints now accept an optional `order_by` array to sort results by one or more fields. Each entry takes a `field` and a `direction` (`asc` or `desc`, defaults to `desc`); multiple entries create a multi-key sort.
    * Brands report sortable fields: `visibility`, `visibility_count`, `mention_count`, `sentiment`, `position`, `share_of_voice`.
    * Domains report sortable fields: `citation_rate`, `retrieval_count`, `citation_count`.
    * URLs report sortable fields: `retrieval_count`, `retrievals`, `citation_count`, `citation_rate`.
  * **`retrieval_count` and `citation_count` on Domains Report** The [Get Domains Report](/api-reference/reports/get-domains-report) endpoint now returns `retrieval_count` (total distinct URL retrievals from the domain across all chats) and `citation_count` (total citations from the domain).
  * **`retrieval_count` on URLs Report** The [Get URLs Report](/api-reference/reports/get-urls-report) endpoint now returns `retrieval_count` — the total number of distinct chats that retrieved the URL.

  ### Deprecated

  * **`retrievals` on URLs Report** The `retrievals` field on [Get URLs Report](/api-reference/reports/get-urls-report) is deprecated. Use `retrieval_count` instead.
</Update>

<Update label="April 22, 2026" description="v0.21.0">
  ### Added

  * **`totalCount` on List Endpoints** The [List Brands](/api-reference/project/list-brands), [List Chats](/api-reference/project/list-chats), [List Prompts](/api-reference/project/list-prompts), [List Tags](/api-reference/project/list-tags), [List Topics](/api-reference/project/list-topics), [List Fanout Search Queries](/api-reference/project/list-fanout-search-queries), and [List Fanout Shopping Queries](/api-reference/project/list-fanout-shopping-queries) endpoints now return a `totalCount` field — the total number of matching results across all pages, for building paginated experiences.
</Update>

<Update label="April 21, 2026" description="v0.20.0">
  ### Added

  * **Get Brand Suggestions Endpoint** New [Get Brand Suggestions](/api-reference/project/get-brand-suggestions) endpoint for listing AI-generated brand suggestions for your project.
  * **Accept Brand Suggestion Endpoint** New [Accept Brand Suggestion](/api-reference/project/accept-brand-suggestion) endpoint to accept a brand suggestion, converting it into a brand.
  * **Reject Brand Suggestion Endpoint** New [Reject Brand Suggestion](/api-reference/project/reject-brand-suggestion) endpoint to reject a brand suggestion, removing it from the project.

  ### Deprecated

  * **`model_id` filters and `model.id` in responses** The `model_id` filter and the `model.id` field in responses are deprecated in favor of [model channels](/api/model-channels). A `model_id` filter is now resolved to its channel (e.g. `gpt-4o` → `openai`) and matches every result on that channel, regardless of the underlying model version. The `model.id` field in responses now always reflects the channel's current model, not the model that originally produced the result. Migrate to `model_channel_id` filters and the `model_channel` object in responses for stable behavior as model IDs are introduced and renamed.
</Update>

<Update label="April 15, 2026" description="v0.19.0">
  ### Added

  * **List Model Channels Endpoint** New [List Model Channels](/api-reference/project/list-model-channels) endpoint returning all available model channels with their current model, description, and active status.
  * **`model_channels` on List Models Endpoint** The [List Models](/api-reference/project/list-models) endpoint now returns a `model_channels` array on each model, listing the channels it belongs to (a model can belong to more than one).
  * **`model_channel` on Chat Endpoints** The [List Chats](/api-reference/project/list-chats) and [Get Chat](/api-reference/project/get-chat) endpoints now return a `model_channel` object. [List Chats](/api-reference/project/list-chats) also accepts an optional `model_channel_id` query parameter for filtering.
  * **`model_channel` on Query Endpoints** The [List Fanout Search Queries](/api-reference/project/list-fanout-search-queries) and [List Fanout Shopping Queries](/api-reference/project/list-fanout-shopping-queries) endpoints now return a `model_channel` object and support `model_channel_id` as a filter.
  * **`model_channel_id` Dimension and Filter on Report Endpoints** The [Get Brands Report](/api-reference/reports/get-brands-report), [Get Domains Report](/api-reference/reports/get-domains-report), and [Get URLs Report](/api-reference/reports/get-urls-report) endpoints now support `model_channel_id` as a dimension and filter, with an optional `model_channel` object in the response.
</Update>

<Update label="April 14, 2026" description="v0.18.0">
  ### Added

  * **`name` field on List Models endpoint** Model objects returned by [List Models](/api-reference/project/list-models) now include a `name` field — a human-readable display name (e.g. ChatGPT, Perplexity).
  * **`channel_title` field on URLs report** The [Get URLs Report](/api-reference/reports/get-urls-report) response now includes an optional `channel_title` field (e.g. YouTube channel name, subreddit).
  * **`mentioned_brands` field on Domains and URLs reports** The [Get Domains Report](/api-reference/reports/get-domains-report) and [Get URLs Report](/api-reference/reports/get-urls-report) endpoints now return a `mentioned_brands` array on each row — a list of brand objects mentioned alongside each domain/URL.
  * **`mentioned_brand_id` filter for Domains and URLs reports** New filter on the [Get Domains Report](/api-reference/reports/get-domains-report) and [Get URLs Report](/api-reference/reports/get-urls-report) endpoints to narrow results by which brands were mentioned in sources. Operators: `in`, `not_in`. Values: array of brand ID strings.
  * **`mentioned_brand_count` filter for Domains and URLs reports** New filter on the [Get Domains Report](/api-reference/reports/get-domains-report) and [Get URLs Report](/api-reference/reports/get-urls-report) endpoints to narrow results by the number of distinct brands mentioned. Operators: `gt`, `gte`, `lt`, `lte`. Value: integer >= 0.
  * **`gap` filter for Domains and URLs reports** New filter on the [Get Domains Report](/api-reference/reports/get-domains-report) and [Get URLs Report](/api-reference/reports/get-urls-report) endpoints to find sources where competitors are mentioned but your own brand is not — useful for identifying content gaps. Operators: `gt`, `gte`, `lt`, `lte`. Value: integer >= 0 (minimum number of competitor mentions).
</Update>

<Update label="April 02, 2026" description="v0.17.0">
  ### Added

  * **Get Topic Suggestions Endpoint** New [Get Topic Suggestions](/api-reference/project/get-topic-suggestions) endpoint for listing AI-generated topic suggestions for your project.
  * **Get Prompt Suggestions Endpoint** New [Get Prompt Suggestions](/api-reference/project/get-prompt-suggestions) endpoint for listing AI-generated prompt suggestions, with optional filtering by `topic_id`.
  * **Accept Topic Suggestion Endpoint** New [Accept Topic Suggestion](/api-reference/project/accept-topic-suggestion) endpoint to accept a topic suggestion, converting it into a regular topic.
  * **Reject Topic Suggestion Endpoint** New [Reject Topic Suggestion](/api-reference/project/reject-topic-suggestion) endpoint to reject a topic suggestion, removing it and its associated prompt suggestions.
  * **Accept Prompt Suggestion Endpoint** New [Accept Prompt Suggestion](/api-reference/project/accept-prompt-suggestion) endpoint to accept a prompt suggestion, creating a new prompt from it.
  * **Reject Prompt Suggestion Endpoint** New [Reject Prompt Suggestion](/api-reference/project/reject-prompt-suggestion) endpoint to reject a prompt suggestion, removing it from the suggestions list.
</Update>

<Update label="March 31, 2026" description="v0.16.0">
  ### Added

  * **Update Prompt Endpoint** New [Update Prompt](/api-reference/project/update-prompt) endpoint allowing you to assign tags and topics to prompts.
  * **Filter Parameters on Get Prompts Endpoint** The [Get Prompts](/api-reference/project/get-prompts) endpoint now supports optional `topic_id` and `tag_id` query parameters, allowing you to filter prompts by topic and tags.
</Update>

<Update label="March 27, 2026" description="v0.15.0">
  ### Added

  * **Prompt Management Endpoints** New [Create Prompt](/api-reference/project/create-prompt) and [Delete Prompt](/api-reference/project/delete-prompt) endpoints for managing prompts via the API.
  * **Brand Management Endpoints** New [Create Brand](/api-reference/project/create-brand), [Update Brand](/api-reference/project/update-brand), and [Delete Brand](/api-reference/project/delete-brand) endpoints for managing brands via the API.
  * **Tag Management Endpoints** New [Create Tag](/api-reference/project/create-tag), [Update Tag](/api-reference/project/update-tag), and [Delete Tag](/api-reference/project/delete-tag) endpoints for managing tags via the API.
  * **Topic Management Endpoints** New [Create Topic](/api-reference/project/create-topic), [Update Topic](/api-reference/project/update-topic), and [Delete Topic](/api-reference/project/delete-topic) endpoints for managing topics via the API.
</Update>

<Update label="March 26, 2026" description="v0.14.0">
  ### Added

  * **`chat_id` Dimension and Filter on Report Endpoints** All report endpoints now support `chat_id` as a dimension and filter.
</Update>

<Update label="March 23, 2026" description="v0.13.0">
  ### Added

  * **Filter Parameters on Get Chats Endpoint** The [Get Chats](/api-reference/project/get-chats) endpoint now supports optional `brand_id`, `model_id`, and `prompt_id` query parameters, allowing you to filter chat results by brand, AI model, and prompt.
  * **`is_own` Property on Get Brands Endpoint** The [Get Brands](/api-reference/project/get-brands) endpoint now returns an `is_own` property on each brand, allowing you to differentiate between your own brands and competitor brands.
</Update>

<Update label="March 19, 2026" description="v0.12.0">
  ### Added

  * **`country_code` Dimension and Filter on Report Endpoints** All report endpoints now support `country_code` as a dimension and filter.
  * **Retrieval Metrics on Domains Report** The [Get Domains Report](/api-reference/reports/get-domains-report) endpoint now returns `retrieved_percentage`, `retrieval_rate`, and `citation_rate` metrics.
  * **Retrieval Metrics on URLs Report** The [Get URLs Report](/api-reference/reports/get-urls-report) endpoint now returns `retrievals` and `citation_rate` metrics.

  ### Deprecated

  * **`citation_avg`, `usage_count`, `usage_rate` on Report Endpoints** These metrics are deprecated and will eventually be removed in a future version. Use the new retrieval metrics instead.
</Update>

<Update label="March 18, 2026" description="v0.11.0">
  ### Added

  * **`date` Dimension on Report Endpoints** The [Get Brands Report](/api-reference/reports/get-brands-report), [Get Domains Report](/api-reference/reports/get-domains-report), and [Get URLs Report](/api-reference/reports/get-urls-report) endpoints now support `date` as a dimension, enabling daily breakdowns of report data within a single API call.
</Update>

<Update label="March 13, 2026" description="v0.10.0">
  ### Added

  * **Get Fanout Search Queries Endpoint** New [Get Fanout Search Queries](/api-reference/project/get-fanout-search-queries) endpoint for retrieving expanded search queries generated during chat conversations, enabling analysis of how AI models fan out user prompts into multiple search queries.
  * **Get Fanout Shopping Queries Endpoint** New [Get Fanout Shopping Queries](/api-reference/project/get-fanout-shopping-queries) endpoint for retrieving shopping-related queries and product data captured in AI model responses, enabling insights into product recommendations and shopping search behavior.
</Update>

<Update label="March 6, 2026" description="v0.9.0">
  ### Breaking Changes

  * **`normalizedUrl` removed from URL Reports** The `normalizedUrl` field has been removed from the [Get URLs Report](/api-reference/reports/get-urls-report) endpoint. URLs in the response are now returned already normalized, making this field redundant.

  ### Changed

  * **Significant Performance Improvements** Report endpoints have been optimized for significantly improved response times across all report queries.
  * **Zero-Visibility Datapoints Included in Brands Report** The [Get Brands Report](/api-reference/reports/get-brands-report) endpoint now returns datapoints for brand + dimension combinations even when they have 0 visibility. Previously, these combinations were omitted from the response.

  ### Added

  * **Filters on Report Endpoints** The [Get Brands Report](/api-reference/reports/get-brands-report), [Get Domains Report](/api-reference/reports/get-domains-report), and [Get URLs Report](/api-reference/reports/get-urls-report) endpoints now support a `filters` array, allowing you to filter results by `model_id`, `tag_id`, `topic_id`, `prompt_id`, `brand_id`, `domain`, and `url` using `in` and `not_in` operators.
  * **`share_of_voice` and `mention_count` added to Brands Report** The [Get Brands Report](/api-reference/reports/get-brands-report) endpoint now returns `share_of_voice` and `mention_count` fields, providing additional brand performance metrics.
</Update>

<Update label="March 4, 2026" description="v0.8.0">
  ### Added

  * **Citation Position on Sources and Position on Brand Mentions in Get Chat API** The [Get Chat](/api-reference/project/get-chat) endpoint now returns `citationPosition` on each source and `position` on each brand mention, providing precise ranking data for citations and brand references in chat responses.
</Update>

<Update label="February 20, 2026" description="v0.7.1">
  ### Added

  * **Citation Count on Sources in Get Chat API** The [Get Chat](/api-reference/project/get-chat) endpoint now returns `citationCount` on each source, providing visibility into how many times a source is cited in the chat response.
</Update>

<Update label="February 19, 2026" description="v0.7.0">
  ### Added

  * **Fanout Search Queries in Get Chat API** The [Get Chat](/api-reference/project/get-chat) endpoint now returns fanout search queries, providing visibility into the expanded search queries generated during chat conversations.
  * **Shopping Products and Queries in Get Chat API** The [Get Chat](/api-reference/project/get-chat) endpoint now returns shopping products and their associated queries, enabling insights into product recommendations and shopping-related search behavior.
</Update>

<Update label="January 27, 2026" description="v0.6.0">
  ### Added

  * **New aggregation attributes in Get Brands Report** The [Get Brands Report](/api-reference/reports/get-brands-report) endpoint now returns additional attributes (`sentiment_sum`, `sentiment_count`, `position_count`, `position_sum`, `visibility_count`, `visibility_total`) enabling more flexible aggregations and analytics calculations.
</Update>

<Update label="January 14, 2026" description="v0.5.0">
  ### Added

  * **URL and Domain Classification field added** The [Get Domains Report](/api-reference/reports/get-domains-report) and [Get URLs Report](/api-reference/reports/get-urls-report) endpoints now return a `classification` field for each domain and URL, providing insights into content categories and types.
</Update>

<Update label="January 13, 2026" description="v0.4.0">
  ### Added

  * **Project Status field added** The [Get Projects](/api-reference/company/get-projects) endpoint now returns a `status` field for each project, enabling better visibility into project lifecycle and state.

  ### Changed

  * **Pagination max limit increased** The maximum pagination limit has been increased from 1,000 to 10,000 records per request, allowing for more efficient bulk retrieval.
</Update>

<Update label="December 22, 2025" description="v0.3.0">
  ### Added

  * **Topics and Tags in Get Prompts API** The [Get Prompts](/api-reference/project/get-prompts) endpoint now returns `tags` and `topics` fields for each prompt, allowing for better categorization and filtering of prompts.
</Update>

<Update label="December 01, 2025" description="v0.2.0">
  ### Added

  * **Topics and Tags as Report Dimensions** Topics and tags are now available as report dimensions in the API, enabling more granular filtering and analysis of report data.
  * **Prompt Volume in Get Prompts API** The [Get Prompts](/api-reference/project/get-prompts) endpoint now returns a `volume` field, providing insight into prompt usage and frequency.
  * **Mentioned Brands in Get Chat API** The [Get Chat](/api-reference/project/get-chat) endpoint now returns a `brands_mentioned` field, providing visibility into which brands are referenced in chat conversations.
</Update>

<Update label="October 09, 2025" description="v0.1.0">
  ### Added

  * **Initial Release** The Peec Customer API is now available.
</Update>


# Filtering and dimensions
Source: https://docs.peec.ai/api/filtering-and-dimensions

How dimensions, filters, and having work on report endpoints, and the pitfalls to avoid.

## Overview

The report endpoints, [Get Brands Report](/api-reference/reports/get-brands-report), [Get Domains Report](/api-reference/reports/get-domains-report), and [Get URLs Report](/api-reference/reports/get-urls-report), all share three controls that shape what you get back:

* `dimensions` Decide how the report is broken down.
* `filters` Decide which underlying chats feed into the numbers (applied **before** aggregation).
* `having` Decide which aggregated results are returned (applied **after** aggregation).

Understanding the difference between these three is the key to getting metrics that mean what you think they mean.

## Dimensions

Every report always breaks down by its own entity: the Brands report returns one result per brand, the Domains report one per domain, the URLs report one per URL. A report with no dimensions returns a single aggregated result per entity. Adding dimensions splits each entity's result into finer slices.

You get one result for **each combination** of the entity and the requested dimension values. For example, on the Brands report, requesting `["tag_id", "model_id"]` returns one result per (brand × tag × model) combination, not one per (tag × model) pair. On the URLs report the same dimensions produce one result per (URL × tag × model), and so on.

Available dimensions include `model_id`, `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `date`, `week`, and `month`.

<Info>
  Always break down by engine (`model_channel_id`) rather than only looking at the aggregate. An overall number can hide that you're strong on one engine and invisible on another.
</Info>

## `filters` vs `having`

Both narrow a report, but they act at different stages and have very different effects on ratio metrics (`share_of_voice`, `visibility`, `retrieval_rate`, `retrieved_percentage`, `citation_rate`).

### `filters`, applied before aggregation

`filters` decide which chats are counted at all. Because they run before the numbers are computed, they shrink **both** the numerator and the denominator of every ratio metric.

Use `filters` when you want to genuinely restrict the scope of the analysis, for example, "only chats from ChatGPT" or "only chats in Germany."

### `having`, applied after aggregation

`having` decide which finished results come back. They run after every metric has already been computed, so they **do not** change any metric's value. They only hide results you don't want to see.

Use `having` when you want to keep the full-population metrics but only display a subset of results.

<Info>
  Population fields (`model_id`, `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`) in `having` require the matching value in `dimensions`, otherwise the field isn't part of the breakdown and the request is rejected.
</Info>

## Pitfall: collapsing share of voice with `filters`

`share_of_voice` is a brand's mentions divided by the mentions of **all** in-scope brands. If you scope to a single brand using `filters`, you remove every other brand from the calculation before it runs, so the denominator becomes just that one brand, and share of voice collapses to `1.0`.

<Warning>
  Filtering by `brand_id` in `filters` always reports `share_of_voice` as `1.0`. That number is meaningless.
</Warning>

To look at one brand while keeping a meaningful share of voice, put `brand_id` in `having` instead:

```json theme={null}
{
  "dimensions": ["model_channel_id"],
  "having": [
    { "field": "brand_id", "operator": "in", "values": ["kw_abc123"] }
  ]
}
```

This returns only that brand's results, but its share of voice is still measured against every brand that appeared in the same scope, which is the value you actually want.

The same principle applies to the Domains and URLs reports: `filters` shrink the denominators behind `retrieval_rate` and `retrieved_percentage`, while `having` selects results without touching them.

## Pitfall: double-counting when you sum across tags yourself

A single prompt can have **multiple tags**, while each prompt belongs to only **one topic**.

When you break a report down by `tag_id`, a chat linked to a prompt with several tags is included in each relevant tag. This is useful when comparing tags individually, because each tag reflects all chats associated with it.

However, you shouldn’t add the results from multiple tags together to calculate a total. Since the same chat can appear under more than one tag, it may be counted multiple times and make the combined total higher than the actual number.

<Warning>
  Never add tag-level results together to calculate a project total. If a chat is tagged with both `enterprise` and `q4-campaign`, it will be counted under each tag, so adding the results would count the same chat twice.
</Warning>

The solution is simple: **let the report handle the aggregation.** Run the report without the `tag_id` dimension, or without any dimensions, and Peec will aggregate across distinct chats so each chat is counted only once.

<CardGroup>
  <Card title="Correct" icon="check">
    Request once without `tag_id`. Each chat is counted a single time.
  </Card>

  <Card title="Incorrect" icon="xmark">
    Request broken down by `tag_id`, then add the results together. Multi-tagged chats are counted once per tag.
  </Card>
</CardGroup>

This applies to every additive value (mention and visibility counts, retrieval counts) and to any ratio you might try to reconstruct from them. If you need both views, per-tag detail and a correct total, make two requests rather than deriving one from the other.

<Info>
  When you do need to combine results across non-overlapping dimensions (such as `model_id` or `date`), use the aggregation formulas documented on each report endpoint rather than naively averaging. Ratio metrics must be recombined from their underlying sums, not averaged.
</Info>


# Introduction to Peec API
Source: https://docs.peec.ai/api/introduction



## Overview

The API provides a way for developers to programmatically work with the same data available in our platform. All endpoints return data in JSON format, ensuring smooth integration with modern apps, services, and workflows.

<Note>
  Access to this API is currently limited to Enterprise customers.
</Note>

## Getting Started

To use the API, you’ll need to generate an API key from your [Account](https://app.peec.ai/api-keys). This key is required for authenticating requests and securing access to your organization’s data.

For more details on how authentication works, see the [Authentication](./authentication) section.


# Model channels
Source: https://docs.peec.ai/api/model-channels

A stable way to reference AI surfaces as underlying models evolve.

## Overview

A **Model Channel** is a stable identifier for a specific AI surface such as ChatGPT UI, Perplexity API, or Google AI Overview that stays constant as the underlying model is upgraded or replaced over time.

Models change frequently (new versions, new names, API-only models becoming UI models), so filtering by `model_id` can cause historical data to fragment across several IDs. Filtering by `model_channel_id` gives you a continuous view of the same surface, regardless of which specific model was powering it on any given day.

<Info>
  Channels are identified by a stable `vendor-index` string such as `openai-0` or `perplexity-1`. The human-readable description (for example, ChatGPT UI) is returned alongside each channel and may be updated over time.
</Info>

## When to use a channel vs. a model

* Use **`model_channel_id`** when you want a stable, long-term view of a surface across model upgrades.
* Use **`model_id`** when you care about the specific model version that produced a response.

A single model may belong to multiple channels when the same underlying model powers more than one surface.

To retrieve the list of available channels, use the [List Model Channels](/api-reference/project/list-model-channels) endpoint.


# Rate Limits for Peec API
Source: https://docs.peec.ai/api/ratelimits



The **Peec AI Customer API** enforces rate limits to ensure reliable and fair usage. Rate limits are applied **per project**.

## Current limits

* **200 requests per minute** per project.

<Warning>
  These limits may be adjusted. Please adhere to the response headers.
</Warning>

If your application exceeds the limit, requests will return a `429 Too Many Requests` response until the window resets.

## Response headers

Every response includes standard rate limit headers so you can monitor usage:

* `X-RateLimit-Limit`: The maximum number of requests allowed in the current window.
* `X-RateLimit-Remaining`: The number of requests remaining in the current window.
* `X-RateLimit-Reset`: The time (in seconds) until the rate limit resets.

Example response headers:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 23
```

## Best practices

* Monitor the rate limit headers in your integration.
* Implement **exponential backoff** or **retry logic** when receiving `429` responses.
* If you need higher limits, [contact support](mailto:support@peec.ai).


# Brand insights
Source: https://docs.peec.ai/brand-insights

Analyze how a single brand performs across topics, models, countries, and competitors.

<img alt="Cleaned13" />

**Brand insights** brings all the data for a specific brand into one place, so you can quickly see where it performs best, where competitors are ahead, and which areas offer the biggest opportunities for improvement.

### **Main KPIs**

A summary of the selected brand’s performance over your chosen time period:

* **Visibility:** Percentage of AI responses where this brand appears.
* **Sentiment:** How positively AI platforms describe this brand (0–100 scale).
* **Position:** Average ranking when this brand appears in AI responses (lower is better).
* **Win rate:** Percentage of AI-generated responses where your brand is ranked first.
* **Share of Voice:** This brand’s share of all brand mentions across your tracked prompts.
* **Strongest / Weakest model:** The AI model where your brand performs best, based on combined visibility, sentiment, and position.

<Tip>
  Change indicators show how each metric moved compared with the previous period of the same length.<br /><br />You can change the brand you are looking at by using the brand filter in the top menu.
</Tip>

### Brand insights graph

The graph shows the brand's performance over time. Toggle between Visibility, Sentiment, Position, Win rate, and Share of Voice to see trends for each.

It also overlays your **retrieved percentage**, so you can see how often your own domains are pulled into AI answers alongside the selected metric. Choose which of your domains to display, and compare brand authority against domain authority over time. Vertical markers on the chart flag events like new prompts being created or an AI model change.

<img alt="BI" />

<Info>
  Switch between Daily, Weekly, or Monthly timeframes using the selectors in the upper-right corner of the graph.
</Info>

### Performance matrix

A configurable matrix that crosses any two dimensions against each other. You control both axes, choosing from:

* **Models** (ChatGPT, Claude, Gemini, etc.)
* **Brands** (competitors)
* **Topics**
* **Tags**
* **Countries**

Pick which metric to view (Visibility, Sentiment, Position, Win rate, or Share of Voice) with the selector in the top-right. Cells are heat-mapped by score, each cell's tooltip shows all four metrics, and you can reorder columns by dragging. For each axis, you can pick exactly which items to show (up to 10), search them, or apply a top-N preset.

For example:

* Which topics does the brand own on ChatGPT but not AI Mode?
* Where is a competitor outperforming my brand, and in which specific markets?

<img alt="Pf" />

<Info>
  Use the actions menu on any section to save or copy the view as an image, or export it as CSV.
</Info>

### Top rankings

Shows how brands rank against each other for a dimension you choose (by AI model, topic, tag, or country). Each column is a rank position, from `#1` through the top brands, and each cell holds the brand sitting at that rank, with your own brand highlighted.

<img alt="Countries BI" />


# Fact-checking
Source: https://docs.peec.ai/brand-perception-fact-checking

What AI says about your brand, compared against the facts you provide, with any claims that contradict your facts highlighted first.

<img alt="Factchecking" />

The [<u>Market</u>](https://docs.peec.ai/brand-perception-market) tab tells you how AI describes your brand, and [<u>Objections</u>](https://docs.peec.ai/brand-perception-objections) tells you what it argues against you. Fact-checking compares what AI said against what you say about yourself, and surfaces the statements your own facts contradict.

It works off two lists. **Claims** are the checkable statements pulled out of your tracked answers. **Facts** are the statements you assert about your brand. A verdict is one claim read against one of your facts.

The unit is a single claim. One answer usually produces several, so a sentence naming your starting price, an integration, and a customer count is three statements that can each be right or wrong on their own. Splitting answers at that grain keeps a wrong price from hiding inside a paragraph that's otherwise correct, and gives a correction one specific thing to fix.

Setting it up takes two steps: first, add the facts your claims will be checked against, then choose which prompts the claims should come from.

<Info>
  **Claims** come from the prompts you select for fact-checking, and only from answers that mention one of your tracked brands. This includes both your own brand and your tracked competitors. A prompt you haven't selected produces no claims; however, its answers often name you.<br /><br />A competitor claim is checked against your facts in the same way as any other claim. However, a verdict is only given when the claim and fact are about the same subject, so facts about your own brand won’t produce a verdict for competitor claims.
</Info>

## Facts

Facts live under **Project settings → Facts**, and they're the premise for everything on this page. Until you have one, nothing can be checked.

<img alt="Image (9)" />

* **Add facts:** Add one statement per line, with up to 50 at a time. Keep each fact short, clear, and easy to verify.

* **Build facts with AI:** Uses the Agent to review your project profile and website, draft checkable facts across your product lines, and show you the suggested facts for review before anything is created.

* **Active or inactive:** Choose whether a fact is included in fact-checking. Turning it off keeps the fact in your list but excludes it from comparisons, so you can keep outdated facts without deleting them.

* **Origin:** Shows whether a fact came from your website or was added manually. You can filter by either origin or search for a specific fact.

* **Edit:** Editing updates the fact and marks it as **Edited**. Deleting removes it completely, and claims will no longer be checked against it. Select several facts to activate, deactivate, or delete them in one go.

Your plan determines how many facts can be active at once. As you add facts, the composer shows how many you’re currently using. Only active facts count toward this limit, so you can deactivate a fact you no longer need to make room for a new one.

<Tip>
  Start with facts that may not be clearly stated on your website, such as your starting price, what each plan includes, supported integrations, and any guarantees you offer.
</Tip>

## Prompts to fact-check

Choose which of your tracked prompts you want to include in Fact-checking. You can select them during setup or later by clicking **Choose prompts** in the page header.

Your plan determines how many prompts you can fact-check at once. The prompt picker shows how many you’ve selected as you go.

Focus on prompts where incorrect information could have the biggest impact on a buyer’s decision, such as pricing questions, plan comparisons, “Is X good for Y?” questions, or prompts used later in the buying journey.

<Info>
  Claims are collected from AI answers generated after you select a prompt. It can take up to a day for claims to start appearing, so allow some time before reviewing your results.
</Info>

## All claims

Each claim is read against your active facts and comes back as one of two:

* **Contradicted:** One of your facts says otherwise. These are the ones worth correcting first.
* **Supported:** One of your facts confirms the claim.

<Info>
  A claim no fact of yours speaks to isn't given a verdict at all, so it doesn't show up as a finding. That's the normal state until the fact base is filled in, and it's why AI can be wrong about you for months without anything appearing here. The **By fact** view is where you see the gap.
</Info>

### Three ways to read it

Choose a view based on what you want to explore: claims that need attention, how claims compare against your facts, or the types of claims AI makes about your brand.

* **Contradicted**: Shows claims that conflict with your facts, giving you a clear list of what to review and correct. Claims are listed newest first, with up to 100 shown.
* **By fact**: Shows each of your facts alongside the claims that have been checked against it. If a fact shows **“Never comes up”**, it means no claims have been matched against that fact yet. This can help you decide whether the fact is relevant or whether you need to track prompts that cover that topic.
* **By group:** Groups claims that make the same point together, while claims that don’t belong to a group appear under **Other claims**. Each group shows the number of **Claims**, the **Chats** they came from, and the share that are **Contradicted**. Open a group to review the individual claims.

<Info>
  A group’s **Claims** and **Chats** numbers include all claims in that group. When you open a group, the claims are shown 15 at a time.

  The **Contradicted share** only includes claims that received a verdict. This means it shows the percentage of checked claims that were contradicted.
</Info>

## Inside a claim

Open a claim to see the full details behind it in one panel.

* **Claim**: Shows the statement and how often the same claim appeared, for example, “Repeated in 12 chats, across 3 prompts and 2 models.”

* **In the answer**: The passage the claim was cut from, quoted from the answer it appeared in.

* **Fact** and **Verdict**: The fact the claim was checked against and the verdict it got. A claim checked against several facts gets a row per fact. If the fact has since been edited, you’ll see the wording that was used when the verdict was given.

* **Prompt**, **Model**, and **Last seen**: Shows where the claim came from: the prompts that produced it, the AI models that made it, and when it was last seen. The first ten prompts are shown, with the rest behind **Show all**.

* **Sources**: The pages behind the claim, each opening its page in Peec. If you want to address an incorrect claim, start here.

* **Change the verdict**: Set the verdict to **Supported**, **Contradicted**, or **Not covered** if you disagree with Peec’s assessment. The claim is then marked **Edited**, and **Restore Peec verdict** puts the original back.

<Tip>
  **Work with AI** hands the claim to the Agent to work out what to do about it. It arrives with the claim, the verdict, the deciding fact, and the prompt already in hand.
</Tip>

## Filtering and export

Use the date range, country, model, topic, and tag filters to narrow down the claims you want to review. **Search claims** lets you look for something specific, such as a price or product name, and searches both the claim itself and the prompt it came from.

You can also filter by verdict in the **By fact** and **By group** views. When you export, the file includes the claims currently loaded on the page, each with the fact it was checked against and its verdict.

## Best practices

* **Fill the fact base before reading the verdicts:** Ten plainly stated facts about price, plan contents, and integrations turn a silent page into real findings.
* **Fact-check the prompts where being wrong is expensive:** A comparison prompt a buyer reads before choosing is worth more here than a broad awareness question.
* **Work contradicted first, then the facts nothing has been checked against:** One is wrong information already in circulation; the other is information you haven't given anyone to check against.
* **Treat pricing, availability, and guarantee claims as the expensive ones:** They're the easiest to verify against your own site and the most costly to have wrong.


# Market
Source: https://docs.peec.ai/brand-perception-market

How AI describes your brand against the market, broken into the attributes models associate with brands in your industry.

<iframe title="YouTube video player" />

When someone asks an AI model about your category, it doesn't just recommend brands, it also describes them. AI might say things like *"great for design teams"* or *"strong on security, but weaker on integrations."* For many users, that description becomes their first impression, and they rarely see the sources behind it.

Peec AI breaks that description into three tabs, each answering a different question:

* **Market**: This page, asks what AI associates with your brand and how that stands against your competitors.
* [**Objections**](/brand-perception-objections): Asks what AI argues against you when a buyer is deciding.
* [**Fact-checking**](/brand-perception-fact-checking): Asks whether what AI says about you is true, measured against facts you state yourself.

<Info>
  All three run on Perception's own set of AI answers rather than your tracked prompts, and all three follow the model filter at the top of the page. [**Brand Insights**](/brand-insights) is separate: it zooms into a single brand and shows how it performs across models, topics, geographies, and competitors.
</Info>

## Attributes

Peec AI breaks AI's view of your brand into **attributes**, the qualities models associate with brands in your industry (for example reliability, performance, value for money, or ease of implementation). Attributes aren't a fixed checklist. Peec extracts them from real AI answers and clusters similar ones together, so the set reflects how your space is actually described. For every attribute you can see how strongly it's associated with your brand and how that compares with your tracked competitors.

Peec asks AI two different questions, and the page keeps them apart because they answer different things:

* **Asked about your brand:** "What is this brand known for?" The answer gives each attribute an **association score** from 0 to 100, where 100 means the attribute always comes up first when AI describes you.
* **Asked about your industry:** "Which brands are known for this attribute?" The answer gives every brand a **market prominence** score from 0 to 100, where 100 means the brand is always named first, and 0 when it is never named.

Both run 0 to 100, but they are not the same number and are not comparable. A brand can be described as "fast" constantly and still lose "fast" to every competitor in the market. That difference is usually the most useful thing on this page.

<img alt="Cleaned3" />

<Tip>
  Scores are averaged across the AI models you track. Use the **model filter** at the top of the page to see how perception shifts on a single model.
</Tip>

## Summary

The page is organized into four sections, moving from a high-level overview to detailed insights.

Starting with a headline that states the finding in a sentence, for example *"AI describes Expedia as Affordability, but it competes best on Adventure Travel"*. Above it, a timestamp shows how long ago the last run finished; hover it for the estimated next run.

Below that you will see:

* **Industry:** The industry your competitors are drawn from. Keep it specific, because it decides which brands you are measured against.
* **Most associated:** The attribute AI reaches for most when asked about your brand. This is the top bar in the chart below it.
* **Best vs competitors:** The attribute where you come closest to the brand leading it, with your position next to it. Position alone isn't the ranking criterion, because attributes attract different numbers of brands, so a `#3 of 12` and a `#3 of 60` aren't the same achievement. Hover for how many attributes you place top three on.
* **Biggest gap:** The attribute AI leans on harder than your market position supports: high when AI is asked about you, low when it is asked about your industry. Shown as two positions, for example `#1 → #9`. `"Unplaced"` means you never surface for it in the market at all, which is the widest version of this gap. It needs at least four attributes carrying both scores.
* **Strongest competitor:** The competitor with the highest average market prominence across all attributes.

<Info>
  Your **selected industry** determines which competitors are included in the analysis.

  Updating the industry in your **project profile** does not automatically rerun the analysis. Hover over the timestamp at the top of the page to see when the next analysis is scheduled to run.<br /><br />Editing your industry for the first time is free, after that you can change it up to three times only,  because each change reruns the full analysis.
</Info>

Below the summary section, you will find the following sections:

* **Brand shape graph:** A radar chart that lets you compare your brand perception against your competitors. Each axis represents an attribute your brand is measured and compared on. You can display up to three brands at once and select which attributes to compare against.
* **How AI describes your brand:** An attribute mention chart that shows the attributes most associated with your brand, sorted by frequency. If the messaging you're investing in doesn't show up here, AI hasn't picked it up yet, and the chats AI cites are where to start looking. These scores answer the **"asked about your brand"** question, so they don't line up with the breakdown below. An attribute can top this chart and still sit near the bottom of the market.
* **Brand comparison by attribute:** A heat map showing how strongly each brand is associated with different attributes, based on the **"asked about your industry"** question. Each cell contains a score from 0 to 100, making it easy to compare brands and see who leads for each attribute. Brands mentioned more consistently score higher than those that appear only occasionally.
* **Attributes and sources**: See every tracked attribute, your ranking for each one, and the sources influencing that position.
  * **Ranking:** Your position compared to other tracked brands for the attribute, based on market prominence. Brands with the same score share the same rank, while a dash means your brand never appeared for that attribute.
  * **Sources:** Expand an attribute to see the pages AI used when describing brands for that quality, with links to the full source details.
  * For each source, you'll also see:
    * **Occurrences:** How often AI cited the source across all Brand Perception checks.
    * **Retrievals:** How many tracked chats retrieved the source during the selected date range.
    * **Citation rate:** The average number of citations per retrieved chat.
    * **URL type and Domain type:** How the source page and its domain are classified.

<Tip>
  Sort by any brand's column, look for attributes where competitors score highly and you don't, and use the filters to control which brands and attributes are shown to answer questions like "Which attributes do we lead on?" and "Where are competitors outperforming us?"
</Tip>

## Best practices

* **Start with the biggest gap:** It names the attribute AI credits you with more than the market does, which is usually more actionable than confirming a strength you already expected.
* **Then read what you're not known for:** An attribute where you place well in the market but AI rarely mentions when asked about you is demand you have already earned and aren't collecting.
* **Check individual models:** A brand can be perceived very differently in ChatGPT than in Gemini, so aggregated results can hide important differences. Use the model filter for the engines that matter most in your industry.
* **Follow attributes to their sources:** Use Attributes and sources to turn a low score into the specific pages worth influencing.


# Objections
Source: https://docs.peec.ai/brand-perception-objections

The arguments AI makes against your brand when a buyer is deciding, grouped by meaning and traced to the pages behind them.

<img alt="Objections2" />

While the **Market** tab shows what AI associates with your brand, **Objections** reveals the reasons AI gives against choosing it.

Peec AI asks every tracked AI model why someone might not choose your brand, repeatedly, then groups the answers by meaning so you can see the objections that come back consistently across models. Each objection carries the sources AI used, so you can find the pages reinforcing it.

<Info>
  Objections uses its own set of AI-generated answers, independent of your tracked prompts. Adding or removing prompts won't affect the results shown here.<br /><br />Use the **model filter** to compare how different AI models argue against your brand. The date range filter does not apply, because the analysis covers every Objections run completed for your brand.
</Info>

The tab has three sections: the **Objection mentions** chart, **Sources behind the view**, and **Terms**.

## Objection mentions

Each bar is an objection, scored from **0** to **100** based on how prominently AI raises it. An objection mentioned first scores 100, and the score drops by 10 points for each lower position in the answer. An objection mentioned tenth scores 10, and anything ranked below tenth scores 0. Answers where an objection isn't mentioned also pull its overall score down, because the score is averaged across every completed run, not only the runs that raised it.

The score reflects both how often an objection appears and how early AI mentions it. A score close to 100 means AI raises that objection consistently and near the beginning of its answers. If an objection has a mid-range score, expand it before drawing conclusions. The same score can mean the objection is raised very early in some answers but not at all in others, or that it's mentioned later in almost every answer. Use the model filter to tell those apart.

<Tip>
  Hover over a bar to view the different phrasings grouped into that objection. The badge shows how many variations it contains, and objections without a badge stand on their own. A grouped objection scores the sum of its phrasings, so it can rank above any one of them.
</Tip>

## Sources behind the view

The objections again, this time as a list with each one's **Score**, expanding into the pages AI retrieved while raising it. A page is tied to the specific objection it supports rather than to the view as a whole.

<img alt="Sourcesobjections" />

Expanding an objection shows these columns:

* **URLs:** The page itself, with a link out to it.
* **URL type** and **Domain type:** How the page and its domain are classified.
* **Mentioned:** Whether your brand appears in the content of the page. A page Peec couldn't read shows as unknown rather than as a No.
* **Occurrences:** How many of that objection's answers cited the page. This comes from the Objections analyses themselves.
* **Retrievals:** How many distinct chats in your tracked prompts retrieved the page. This comes from your regular prompt tracking, so it counts every context the page surfaced in, not only the ones where AI argued against you.
* **Citation rate:** The average number of times this page was cited when it was retrieved. This is an average, so it can be greater than 1.

<Info>
  **Retrievals** and **Citation rate** come from your tracked prompts, so a page you don't track shows a dash in both, and its row won't open. A page can have high Occurrences and still show a dash for Citation rate: AI used it in the Objections analyses, but it hasn't appeared in your tracked prompts yet, so there's nothing to average.
</Info>

<Tip>
  Click a tracked page to open it in Peec, where you can see the prompts and chats it appears in. For an untracked page the row is inert, so use the link in the **URLs** column to open the page itself.
</Tip>

## Terms

The exact words AI used when arguing against you: each **Term**, the **Objection** it was grouped into, its **Occurrences**, and the **Models** that used it. Search it when you're checking for a specific phrase, and sort by Occurrences to see which wording comes up most.

## Best practices

* **Read the sources before taking action:** An objection is only actionable once you know which pages AI is drawing it from.
* **Check the phrasings behind a bar:** The grouped terms often show the objection is narrower, or broader, than its label suggests.
* **Investigate mid-range scores:** Use the model filter to see whether an objection is driven by one AI model or appears consistently across all models.
* **Separate the true objections from the false ones:** A false objection is a content and PR problem. A true one is product feedback you rarely get any other way.


# Connecting your data
Source: https://docs.peec.ai/connecting-your-data



Crawl Insights works on your server logs. Connect a data source, and Peec AI identifies AI bot visits in your traffic, categorizes each bot, and keeps your dashboard up to date.

There are eight ways to connect. Pick the one that matches your hosting setup:

| Integration | How it connects |
| :- | :- |
| [AWS CloudFront](#aws-cloudfront) | CloudFormation stack deployed into your AWS account |
| [Google Cloud CDN](#google-cloud-cdn) | One-line setup script for your GCP project |
| [Cloudflare](#cloudflare) | Worker deployed to your zone |
| [Vercel](#vercel) | Log Drain on your Vercel team |
| [WordPress](#wordpress) | Plugin installed on your site |
| [Akamai](#akamai) | DataStream created via the Akamai API |
| [Generic webhook](#generic-webhook) | Your system posts logs to a Peec endpoint |
| [File upload](#file-upload) | Upload a CSV or CLF log file directly |

You can manage or disconnect your data source at any time from **Settings**.

<Info>
  Every integration filters your traffic the same way: only requests from known AI crawlers and agents are stored; all other traffic is discarded at ingest. See the [supported AI bots](#supported-ai-bots) below.
</Info>

## AWS CloudFront

Peec AI deploys a CloudFormation stack into your AWS account. The stack receives your CloudFront access logs, filters them for AI crawler traffic, and forwards the matching entries to Peec automatically.

You'll need permission to deploy CloudFormation stacks, plus your CloudFront Distribution ID(s).

1. Select your **AWS region** in Peec.
2. Click **Open in AWS Console**. A CloudFormation quick-create page opens with all parameters pre-filled.
3. Deploy the stack. This usually takes 1 to 2 minutes.
4. Back in Peec, enter your **CloudFront Distribution ID(s)**, comma-separated if you have several.

The status changes to **Stack deployed** once the integration is live.

## Google Cloud CDN

Peec AI generates a one-line setup command pre-filled with your credentials. Running it configures a Cloud Logging sink and deploys a Cloud Function that filters your CDN access logs and forwards AI crawler traffic to Peec.

You'll need a GCP project with permission to enable APIs, create Pub/Sub topics, and deploy Cloud Functions, plus your Cloud Load Balancer URL map name.

1. Select your **GCP region** in Peec.
2. Copy the generated setup command.
3. Run it in your terminal or **Google Cloud Shell**. The script asks for your **Cloud Load Balancer URL map name**, then completes setup and activates the integration.

The status moves from **Awaiting activation** to **Integration active**.

## Cloudflare

Peec AI uses your Cloudflare API token to deploy a Worker to your selected zone. The Worker captures AI crawler requests in real time and forwards them to Peec without affecting your site's response times.

### Create an API token

<Frame>
  <img alt="Connecting To Cloudflare" />
</Frame>

1. Navigate to your profile in Cloudflare
2. Select **API Tokens** from the left-hand panel
3. Select **Create Token** and click on **Get Started** (the first option)
4. Give your token a name
5. Add three permission fields by clicking on **Add More** under the permission section. From there, you need to add in this order:
   1. **Workers Scripts > Edit**
   2. **Zone > Zone > Read**
   3. **Zone > Workers Routes > Edit**
6. No need to edit anything else; you can continue to the summary and click on **Create Token**

### Deploy the Worker

1. Enter your **Cloudflare API token** in Peec and press **Enter** to validate it.
2. Select your **Zone** from the dropdown.
3. Click **Deploy worker**.

The Worker goes live immediately across all requests to that zone.

### Cloudflare Worker limits

When you connect through Cloudflare Workers, every request your site receives, including from AI bots, counts toward your Workers request quota.

All Cloudflare accounts include the Workers Free plan by default, which allows up to 100,000 requests per day and resets daily. This limit applies regardless of your Cloudflare site plan, because Business and Enterprise site plans are separate from the Workers plan. On high-traffic sites, this limit can be reached quickly.

Once the limit is hit, two things can happen:

* **Peec stops receiving log data:** For the remainder of that day, Peec stops receiving any log data coming from your domain, resulting in gaps in your Crawl Insights.
* **Errors to visitors:** Cloudflare routes requests to Fail Closed by default, meaning that once the limit is hit, Cloudflare serves a [1027 error page](https://developers.cloudflare.com/workers/platform/limits/#daily-requests) instead of your site.

What to do in these cases:

* **Enable minimum safeguard:** In your Cloudflare dashboard, set the route mode to **Fail Open**. Your site will remain accessible to visitors, though data collection will still be paused for the rest of the day.
* **Upgrade to a Workers Paid plan:** The Workers Paid plan removes the daily request cap, ensuring uninterrupted log ingestion and continuous data in Crawl Insights. You can find Cloudflare's [pricing page](https://developers.cloudflare.com/workers/platform/pricing/) for details.

## Vercel

Peec AI uses a Vercel **Account API token** (a personal access token, not an AI Gateway key) to create a Log Drain on your selected team. Vercel streams access logs directly to Peec, where they're filtered for AI crawler traffic.

You'll need an API token generated from your Vercel account, with access to the team you want to monitor.

1. In Vercel, go to **Account Settings → Tokens** ([vercel.com/account/tokens](http://vercel.com/account/tokens)) and create a token. (Do not use a key from **AI Gateway → API Keys**, that's a separate credential for calling AI models and won't work here.)
2. Enter your Vercel API token in Peec and press Enter to validate it.
3. Select your **Team** from the dropdown.
4. Select the **Projects** to monitor, or choose **All projects**.
5. Click **Deploy drain**.

## WordPress

Peec AI generates a WordPress plugin pre-configured with your organization's credentials. Once activated, the plugin logs AI crawler visits to Peec without impacting your site's performance. It skips internal WordPress paths (health checks, admin AJAX, cron) and correctly identifies visitor IPs when your site sits behind a proxy or CDN.

1. Click **Download plugin** in Peec. A `.zip` file is generated with your credentials embedded.
2. In your WordPress admin panel, go to **Plugins → Add New → Upload Plugin**.
3. Upload the `.zip` file and click **Activate Plugin**.

The plugin confirms the connection on activation, and the status changes to **Plugin active**.

## Akamai

Peec AI uses your Akamai EdgeGrid credentials to create a DataStream via the Akamai API. The stream delivers access logs to Peec every 30 seconds.

You'll need the EdgeGrid credentials from your `.edgerc` file: **Host**, **Client Token**, **Client Secret**, and **Access Token**.

1. Enter your Akamai EdgeGrid credentials in Peec and press **Enter** to validate them.
2. Select a **Group** from the dropdown.
3. Select the **Properties** to monitor.
4. Click **Deploy DataStream**.

## Generic webhook

If your provider isn't listed above, you can send logs to Peec yourself. Peec AI gives you a webhook endpoint and an API key. You configure your own system, whether that's a CDN, log shipper, reverse proxy, or custom application, to POST access log batches to the endpoint. Peec validates each payload and keeps the AI crawler traffic.

1. Click **Generate API Key** in Peec.
2. Click **Reserve API Key** to lock it in.
3. Copy the **Webhook URL** and **required headers**.
4. Configure your system to POST log batches to the endpoint.
5. Click **Confirm webhook deployment**.

<Info>
  Regenerating the API key invalidates the previous one. Update your sender configuration before switching keys.
</Info>

### Endpoint

```text theme={null}
POST https://api.peec.ai/agent-analytics/generic-access-log
```

### Required headers

```text theme={null}
Authorization: Bearer <your-api-key>
x-org-id: <your-organization-id>
Content-Type: application/json
```

### Request body

Send an array of log objects, with a maximum of **500 entries per request**.

```json theme={null}
[
  {
    "timestamp": "2024-01-15T12:34:56Z",
    "request_method": "GET",
    "request_url": "https://example.com/blog/my-post",
    "response_status": 200,
    "user_agent": "GPTBot/2.0",
    "country_code": "US",
    "client_ip": "1.2.3.4",
    "referer": "https://some-site.com/"
  }
]
```

| Field | Type | Required | Notes |
| :- | :- | :- | :- |
| `timestamp` | string | Yes | ISO 8601 datetime |
| `request_method` | string | Yes | e.g. `GET`, `POST` |
| `request_url` | string | Yes | Full URL including scheme and host |
| `response_status` | number | Yes | HTTP status code (100–599) |
| `user_agent` | string | Yes | Raw User-Agent header value |
| `country_code` | string | No | ISO 3166-1 alpha-2 |
| `client_ip` | string | No | IPv4 or IPv6 |
| `referer` | string | No | Referring URL |

## File upload

To analyze a specific time period, or if you'd rather not set up a live connection, upload a log file directly from your browser. Peec parses the file, finds the AI crawler entries, and imports them into your dashboard.

1. Drag and drop your log file (`.csv` or CLF `.log`), or browse for it.
2. For CLF files, enter your **domain** (e.g. `example.com`) when prompted, so Peec can build full URLs from the request paths.
3. Peec processes the file and shows how many AI bot requests it found.
4. Click **Upload** to import them. A progress bar tracks completion.

### CSV format

Column order doesn't matter:

| Column | Required | Notes |
| :- | :- | :- |
| `timestamp` | Yes | ISO 8601 datetime |
| `request_method` | Yes | e.g. `GET` |
| `response_status` | Yes | HTTP status code |
| `user_agent` | Yes | Raw User-Agent string |
| `request_url` | Yes | Full URL |
| `client_ip` | No | IPv4 or IPv6 |
| `referer` | No | Referring URL |
| `country_code` | No | ISO 3166-1 alpha-2 |

Example:

```text theme={null}
timestamp,request_method,response_status,user_agent,request_url
2024-01-15T12:34:56Z,GET,200,GPTBot/2.0,https://example.com/blog/post
```

### Common Log Format (Apache / Nginx)

```text theme={null}
1.2.3.4 - - [15/Jan/2024:12:34:56 +0000] "GET /path HTTP/1.1" 200 1234 "https://referer" "GPTBot/2.0"
```

## Supported AI bots

All integrations detect and track the following AI crawlers and agents. Only requests whose User-Agent matches one of these are stored.

| Bot | Description |
| :- | :- |
| GPTBot | OpenAI web crawler |
| ChatGPT-User | ChatGPT browsing requests |
| OAI-SearchBot | OpenAI search crawler |
| ClaudeBot | Anthropic web crawler |
| Claude-Web | Anthropic browsing (legacy) |
| Claude-SearchBot | Anthropic search crawler |
| Claude-User | Claude browsing requests |
| Claude-Code | Claude Code agent |
| anthropic-ai | Anthropic general crawler |
| PerplexityBot | Perplexity AI crawler |
| Perplexity-User | Perplexity browsing requests |
| Google-Extended | Google AI training crawler |
| Google-CloudVertexBot | Google Vertex AI crawler |
| Google-Agent | Google AI agent |
| GoogleAgent-Mariner | Google Mariner agent |
| Gemini-Deep-Research | Google Gemini deep research agent |
| Meta-ExternalAgent | Meta AI agent |
| meta-webindexer | Meta web indexer |
| meta-externalfetcher | Meta external fetcher |
| FacebookBot | Meta/Facebook crawler |
| Applebot | Apple web crawler |
| Applebot-Extended | Apple AI training crawler |
| Amazonbot | Amazon web crawler |
| Amzn-SearchBot | Amazon search AI crawler |
| AzureAI-SearchBot | Microsoft Azure AI crawler |
| GrokBot | xAI Grok crawler |
| Grok-DeepSearch | xAI Grok deep search agent |
| xAI-Grok | xAI Grok agent |
| DeepSeekBot | DeepSeek AI crawler |
| MistralAI-User | Mistral AI browsing requests |
| cohere-ai | Cohere AI crawler |
| cohere-training-data-crawler | Cohere training data crawler |
| PanguBot | Huawei PanGu crawler |
| Ai2Bot | Allen Institute for AI crawler |
| Ai2Bot-Dolma | Allen Institute Dolma dataset crawler |
| CCBot | Common Crawl bot |
| Bytespider | ByteDance/TikTok crawler |
| Diffbot | Diffbot AI crawler |
| DuckAssistBot | DuckDuckGo AI assistant crawler |
| YouBot | You.com crawler |
| quillbot.com | QuillBot AI crawler |
| Webzio-Extended | Webz.io extended crawler |
| omgili | Webhose/Omgili crawler |
| omgilibot | Webhose/Omgili bot |
| Timpibot | Timpi search crawler |
| NovaAct | Amazon Nova Act agent |
| Manus-User | Manus AI agent |
| MyCentralAIScraperBot | MyCentral AI scraper |
| Brightbot | Bright Data crawler |


# Content optimization
Source: https://docs.peec.ai/content-optimization

Review suggested changes to your content, edit your draft, and export it for publication.

**Content optimization** turns an Action for one of your pages into an editable draft you can work on directly in Peec AI. It highlights areas that could be improved and suggests changes to help optimize your content.

Open a Content optimization Action and click **Optimize content** to review the suggestions and edit your page directly in the workspace.

<Info>
  You’ll only see **Add content** and **Optimize content** when Content optimization is enabled for your account.
</Info>

## Add a page yourself

You don’t have to wait for Peec to surface a page for optimization. If you already know which page you want to improve, click **Add content** in the **Actions** header to create a **Content optimization** Action for that page.

To create the Action, provide:

* **A URL or a document:** Add the URL of a live page, such as `yoursite.com/page`, or upload a Markdown (`.md` or `.markdown`) file for content that hasn’t been published yet.
* **Page type:** Tell Peec AI what type of page it’s optimizing.
* **Topic and Prompt:** Choose the topic, then the prompt you want to optimize the page for. Only topics that already contain prompts can be selected.

<Tip>
  If the **WordPress** tab is available to your account, you can also connect your site and select an existing page or post to optimize.<br /><br />Click **Generate action** to create it. Once it’s ready, the Action will appear under **New**, where you can open it and start optimizing your content.
</Tip>

## Working through the workspace

Peec AI's suggestions appear on the left, with your page content on the right.

1. **Review the Suggestions tab:** Suggestions are grouped by passage. Click one to jump to the relevant part of your article and review the recommended change.
2. **Apply or dismiss a rewrite:** Use **Apply** to add a drafted change to your article, or **Dismiss** to keep the existing content. Suggestions that need new text can be worked through individually.
3. **Edit the content directly:** You can also rewrite a passage yourself using the rich-text editor. Select text to access the available formatting options.
4. **Check the Outline tab:** Review your article’s headings and click a heading to jump to that section. The outline reflects headings you add or change in the article.
5. **Review SEO checks when available:** The **SEO** tab shows checks from the source page, including which passed and which need attention. It only appears when the page has check results. Editing the article does not update these results.

<Tip>
  Click a suggestion in the panel to jump to and highlight the relevant passage in the article. You can also click a highlighted passage in the article to open its corresponding suggestion in the panel.
</Tip>

### The suggestions panel

* **Filter:** Switch between **To review**, **Applied**, and **Dismissed** to review suggestions based on their status. The heading above the list shows which set you’re viewing and how many suggestions it contains.
* **Apply:** Adds the suggested change to your article. **Dismiss** keeps your existing content instead.
* **Revert:** Appears after you’ve applied or dismissed a suggestion and lets you undo that decision, returning the suggestion to **To review**.

<Info>
  **Apply all** and **Dismiss all** appear in the **Suggestions** panel while you’re viewing **To review** and drafted rewrites remain. These controls handle the remaining drafted rewrites together.
</Info>

### Work with the Agent

If you have AI editing access, use **Work with AI** on a prepared rewrite or passage, or **Write with AI** when suggested content still needs writing. These controls prepare a request for the Agent with the relevant context. You can also select text in the article and choose **Ask AI**.

Review the request, add any instructions, and send it. The Agent can edit the draft in the workspace. Review the resulting changes before publishing.

## Work with your AI assistant

If you've connected your AI assistant through the [Peec AI MCP Server](/mcp/introduction), it can work through a Content optimization Action for you. It can read the article and its suggestions, apply or dismiss Peec's rewrites, and write the passages that suggestions only describe.

Ask it in plain language, such as *"Apply the pricing suggestions on our pricing page optimization"*, or run the [`peec_optimize_content`](/mcp/prompts#peec-optimize-content) prompt to work through everything that's pending. Your assistant's changes appear in the workspace as tracked edits under your name, and you can revert them like your own.

<Info>
  Reading an article works for any project member. Editing it needs company member access. See the [MCP tools reference](/mcp/tools#get-optimize-content) for details.
</Info>

## Export your content

When you’re ready to take your draft out of Peec AI:

* **Copy:** Copies the article as plain text to your clipboard.
* **Download:** Exports the article as **HTML (.html)** or **Plain text (.txt)**.

Apply the rewrites you want to keep before exporting. Suggestions you haven’t applied retain the original wording in the exported article.

If the article is linked to WordPress and publishing is available to your account, click **Publish to WordPress**. Choose **Save as draft** to keep the published page unchanged, or **Publish live** to replace it with the updated content.


# Crawl insights
Source: https://docs.peec.ai/crawl-insights

Agent Analytics gives you visibility into AI bot activity on your website. Using first-party data from your server logs is the most direct signal of how AI bots access your content.

<iframe title="YouTube video player" />

[Watch "Agent Analytics - Peec AI" on YouTube](https://youtu.be/xr099LCVWhg)

Crawl Insights reveals AI bot activity directly from your server logs, showing which bots access which pages and folders, how often they visit, the status codes they receive, and how all of this links to your AI visibility.

To get started, go to **Crawl Insights** in the side panel and connect a data source. Peec AI supports automated integrations for **AWS CloudFront**, **Google Cloud CDN**, **Cloudflare**, **Vercel**, **WordPress**, and **Akamai**, plus a **generic webhook** and direct **CSV/CLF file upload**. The setup steps for every option are in [Connecting your data](https://docs.peec.ai/connecting-your-data).

Once connected, Peec AI identifies AI bot hits in your logs, categorizes each bot, and populates the dashboard. You can manage or disconnect your data source at any time from **Settings**.

## Dashboard overview

Once the data is loaded, your dashboard appears. From here, you can access key information and use different tools to analyze your data.

<img alt="Cleaned9" />

The dashboard shows:

* **Filters:** Date, Platform (e.g., OpenAI, Google), Bot type (Training, Search, User Query, Other), and Bot (e.g., GPTBot, ClaudeBot).
* **KPI summary:** A row of key metrics at the top gives a snapshot of your filtered data: total bot visits, active bots, and failure rate (the proportion of requests that returned an error, 4xx or 5xx).
* **Crawl activity over time:** A line chart of AI bot visits, with a separate line for each AI model. Switch between hourly (only in a 3-day view), daily, weekly, and monthly; daily is the default. Use it to spot trends, sudden spikes, or unexplained drops in bot activity.
* **Content section:** Further down, you'll see AI bot traffic broken down by folder and URL, showing which parts of your site AI bots visit most.

### Crawl breakdown

<img alt="Image" />

The crawl breakdown shows bar charts that break down bot visits by different dimensions:

* **Platform**: The AI vendor (e.g., OpenAI, Anthropic, Google).
* **Bot**: The specific user agent (e.g., GPTBot, ClaudeBot, PerplexityBot).
* **Bot type**: Training / Search / User query / Other.

<Info>
  The **Bot type** indicates the purpose of the crawl:

  * Training bots collect data to build or refine AI models.
  * Search bots crawl the web and index web pages to surface in AI search results.
  * User Query bots access your website to fetch content on behalf of a user.
</Info>

## Detailed insights

Insight Details gives a URL-level breakdown of AI bot activity and source performance. Open it from the in-page navigation bar, or by clicking **See details** above the By URL chart.

Here you will see:

* **Filters:** The same global filters apply (date range, platform, bot type, bot). Within the table, you can also filter by folder (drill into a specific section of your URL structure) and status code (show only URLs that returned a specific HTTP response (e.g., 200, 404, 500)). You can also use the table's search bar to quickly find a specific URL.
* **KPI summary:**
  * **Total bot visits**: Total requests across all URLs in the selected filters.
  * **Active bots**: Number of distinct bots active in this view.
  * **Failure rate**: Proportion of requests that returned an error (4xx or 5xx status code).
  * **Top-visited folder**: The top-level section of your site (e.g., /blog/, /products/) receiving the most bot visits.
  * **Top-visited URL**: The single URL receiving the most bot visits.

### Visited URLs table

This table shows the pages on your site that can be crawled and indexed, with details for each: which pages receive bot visits, how often, and how that varies across the bots visiting them.

You'll see:

* **URL**: The requested page path from your domain.
* **Folder**: The primary section or directory the URL belongs to.
* **Bot visits**: Total AI bot visits to this URL in the selected period.
* **Platforms**: Bot visits by the vendor behind the bots requesting the URL.
* **Status codes**: The HTTP response the server returned to bots.

Based on your prompt data, you'll also see:

* **Retrievals**: The total number of times this URL appeared as a source in AI chat responses.
* **Citation rate**: The average number of inline citations per chat when this URL is retrieved as a source.
* **Topics**: How many of your tracked topics had prompts where this page appeared as a source.

<Info>
  Prompt data comes from the prompts you are tracking. It is not influenced by AI bot activity.
</Info>

## Settings

Under **Settings**, you can manage your connection to Cloudflare or any other provider. To switch providers, disconnect and reconnect to keep the migration seamless and avoid data gaps.

You can also delete all of your log file data. This action is irreversible; the data cannot be recovered.

<img alt="Crawlinsightsconnect" />

## Status codes

Status codes show how your server responded to AI bot visits, based on your connected log data. The overview table always shows a baseline set of status codes, even when they have zero visits in your logs. Additional codes appear only when present in your logs.

| Status code | Description |
| :- | :- |
| 200 | OK |
| 301 | Moved Permanently |
| 302 | Found (Temporary Redirect) |
| 304 | Not Modified |
| 307 | Temporary Redirect |
| 308 | Permanent Redirect |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 410 | Gone |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
| 502 | Bad Gateway |
| 503 | Service unavailable |
| 504 | Gateway Timeout |

## FAQs

<AccordionGroup>
  <Accordion title="How do I connect?">
    Go to **Crawl Insights** and follow the setup prompt. The method depends on your hosting setup:

    * If your site runs on **AWS CloudFront, Google Cloud CDN, Cloudflare, Vercel, WordPress, or Akamai**, use the automated integration for your provider.
    * If your provider isn't listed, send logs via the **generic webhook**, or upload a CSV or CLF **log file** directly.

    Setup steps for every option are in [Connecting your data](/connecting-your-data).
  </Accordion>

  <Accordion title="How do I disconnect?">
    Go to **Crawl Insights → Settings**. You'll find the disconnect option in the danger zone. Disconnecting stops log syncing. Disconnecting does not automatically delete historical data.
  </Accordion>

  <Accordion title="What plans are agent analytics available on?">
    Crawl Insights is currently available on all plans, with monthly bot visit limits based on your plan:

    **Brands**

    * **Starter:** 4M bot visits/month
    * **Pro:** 10M bot visits/month
    * **Advanced:** 25M bot visits/month
    * **Enterprise:** Custom limit

    **Agency**

    * **Essential:** 10M bot visits/month
    * **Growth:** 25M bot visits/month
    * **Scale:** 45M bot visits/month
    * **Comprehensive:** Custom limit

    The limit applies at the **company level**, not per project. Once your company reaches its monthly limit, Crawl Insights stops storing new data for the rest of that month.

    This may create a gap in your Crawl Insights data. A gap does not necessarily mean that AI bots did not visit your website during that time; it simply means that your monthly limit has been reached.

    Data collection and storage automatically resume at the start of the following month.
  </Accordion>

  <Accordion title="Does my Cloudflare plan affect how much data is collected?">
    Yes. If you're on Cloudflare's free plan, your Worker is limited to 100,000 requests per day. On high-traffic sites, this may mean not all bot requests are captured. Upgrading to a paid Cloudflare Workers plan removes this limit.
  </Accordion>

  <Accordion title="Can I request my data to be deleted?">
    You can request the deletion of your data at any time by contacting our support team or navigating to settings in the danger zone.
  </Accordion>
</AccordionGroup>

## Privacy policy

To read our privacy policy, see the [Privacy Policy for Peec AI](https://peec.ai/legal/privacy-policy)


# Crawlability
Source: https://docs.peec.ai/crawlability



**Crawlability** shows which AI bots are allowed or blocked from accessing a website based on its `robots.txt` file. Simply select a tracked domain to see the results instantly, with no additional setup or account connection required.

<img alt="Image" />

Peec AI checks the domain’s `robots.txt` against **40+ AI bots from 20+ vendors** and shows the crawlability status for each one.

Bot categories are based on publicly available information about their intended purpose. As more information about how these bots operate becomes available, Peec may update their classifications to keep them accurate.

## Crawlability table

The table breaks down the status for each bot:

* **Bot**: The user-agent identifier (e.g., GPTBot, ClaudeBot).
* **Platform**: The AI vendor behind the bot (e.g., OpenAI, Anthropic, Google).
* **Bot type**: Training, Search, User Query, and Other.
* **Status**: Allowed, Partial, or Blocked.
* **Reason**: How the status was determined: explicit rules for this bot, or inherited from the global wildcard (\*) rules.

<Info>
  Use the in-table search bar to find a specific bot, or filter by platform, bot type, or status using the filters at the top.
</Info>

## URL tester

<Frame>
  <img alt="Crawlability URL Tester" />
</Frame>

Enter any URL from your domain to check which AI bots are allowed or blocked by its `robots.txt` rules.

Select a URL from your domain to see which AI bots are allowed or blocked from crawling it. Use these insights to identify any bots that may be unintentionally blocked and update your `robots.txt` rules where needed.

## Interpreting crawlability

If an AI bot is blocked, it can’t crawl or access the content on that page, which may prevent your site from being used as a source in its responses.

Use **Crawlability** to:

* **Identify accidental blocks** that could limit your visibility in AI responses.
* **See which AI bots can access your content** and which are restricted.
* **Confirm robots.txt changes** to make sure your updated rules are working as intended.

## Bots

**Bots** show which AI bots are visiting your pages, which vendors they belong to, and the type of each bot.

| AI bot | Platform | Type | Purpose / Note |
| :- | :- | :- | :- |
| YouBot | [You.com](http://You.com) | Other | Fetches pages to power [You.com](http://You.com)'s AI search results. |
| omgili | [Webz.io](http://Webz.io) | Training | Forum and discussion crawler for structured dataset building. |
| Perplexity-User | Perplexity | User Query | Used during a user's Deep Research session. |
| Amazonbot | Amazon | Training | General training for Titan/Olympus models. |
| Google-Agent | Google | User Query | Used by Google agents to navigate the web and perform actions upon user request (e.g. Project Mariner). |
| cohere-training-data-crawler | Cohere | Training | Specialized crawler for raw training data. |
| ClaudeBot | Claude (Anthropic) | Training | Official training bot for Anthropic models. |
| Gemini-Deep-Research | Google | User Query | High-intensity agent for user-requested research. |
| Google-CloudVertexBot | Google | Search | Crawling for Google Cloud Vertex AI services. |
| Google-Extended | Google | Training | Opt-out token for Gemini training and AI product improvement. |
| PanguBot | PanGu (Huawei) | Training | Training for Huawei's Pangu models. |
| ChatGPT-User | ChatGPT (OpenAI) | User Query | Visits links directly provided by a user. |
| CCBot | Common Crawl | Training | Massive open-source web archive for AI labs. |
| GrokBot | Grok (xAI) | Training | Real-time web search and training for Grok 3/4 models. |
| DuckAssistBot | DuckDuckGo | User Query | Summarizes pages for DuckDuckGo's AI responses. |
| omgilibot | [Webz.io](http://Webz.io) | Other | Forum-specific crawler variant. Commercial data product. |
| Diffbot | Diffbot | Training | Structured data extraction as a service. |
| GoogleAgent-Mariner | Google | User Query | Action Agent: Can fill forms and click buttons. |
| TikTokSpider | ByteDance | Other | Specialized scraper for TikTok's AI data. |
| Webzio-Extended | [Webz.io](http://Webz.io) | Training | Large-scale data scraping for AI providers. |
| Bytespider | ByteDance | Training | Training for TikTok and ByteDance AI. |
| Applebot-Extended | Apple | Training | Used for training Apple's generative features. |
| OAI-SearchBot | ChatGPT (OpenAI) | Search | Real-time retriever for ChatGPT answers. |
| DeepSeekBot | DeepSeek | Training | Training for the DeepSeek model series. |
| PerplexityBot | Perplexity | Search | Fact-checking and retrieval for Perplexity. |
| Claude-Web | Claude (Anthropic) | Other | Legacy bot for web browsing during Claude interactions. |
| Grok-DeepSearch | Grok (xAI) | Search | Real-time web search for Grok's deep research feature. |
| Ai2Bot-Dolma | Allen Institute | Training | Specifically builds the Dolma open dataset. |
| Manus-User | Butterfly Effect | User Query | Action Agent: Navigates and interacts with sites. |
| FacebookBot | Meta | Training | Web crawler used by Meta for AI training data collection. |
| AzureAI-SearchBot | Microsoft | Search | Web retrieval for Azure AI services. |
| xAI-Grok | Grok (xAI) | Search | General-purpose web search bot for xAI/Grok. |
| Timpibot | Timpi | Training | Decentralized search engine for AI. |
| Claude-SearchBot | Claude (Anthropic) | Search | Anthropic's specific bot for its search features. |
| MistralAI-User | Mistral | User Query | On-demand browser for Mistral users. |
| Claude-User | Claude (Anthropic) | User Query | Triggered when a user prompts with a specific link. |
| Amzn-SearchBot | Amazon | Search | Search bot for Amazon's AI shopping features. |
| MyCentralAIScraperBot | Unknown | Other | Centralized AI data collection tool. |
| GPTBot | ChatGPT (OpenAI) | Training | Primary crawler for foundational training. |
| anthropic-ai | Claude (Anthropic) | Training | General data collection and model training. |
| meta-webindexer | Meta | Search | Search indexing for Meta's AI assistants. |
| NovaAct | Amazon | User Query | Agent for automated web-based workflows. |
| meta-externalfetcher | Meta | User Query | Used for real-time link expansion on Meta. |
| CloudVertexBot | Google | Training | Cloud-based AI deployment and indexing. |
| Ai2Bot | Allen Institute | Training | General-purpose web crawler for Allen Institute AI research. |
| Meta-ExternalAgent | Meta | Training | High-velocity training crawler for Llama. |
| [quillbot.com](http://quillbot.com) | QuillBot | User Query | Fetches content to power QuillBot's AI writing tools. |
| Applebot | Apple | Search | Gathers data to power Spotlight, Siri, and Safari search functionality. |
| cohere-ai | Cohere | Training | Training for enterprise-grade LLMs. |
| Brightbot | Bright Data | | |


# Domains
Source: https://docs.peec.ai/domains



<img alt="Image" />

In the **Domains** page, you’ll see:

* **Source retrievals over time:** Shows how retrievals change over time for the top five domains. Hover over the graph to identify each domain and see how its retrievals change across your selected timeframe.
* **Domain movers:** Lists domains sorted by number of retrievals. You can switch between different views:
  * **Top:** Domains with the highest number of retrievals in the selected timeframe.
  * **New:** Domains retrieved for the first time in the selected timeframe.
  * **Trending:** Domains showing the fastest growth in retrieval activity.
  * **Losing:** Domains showing the largest decline in retrieval activity.
* **Domain type:** Shows all domains AI models used when generating answers to your prompts, grouped by type, such as **Editorial, Corporate, UGC, Reference, Competitor,** and **Institutional**.

## Domain table

Detailed breakdown of domain visibility across AI responses:

* **Source:** The domain name of the website.
* **Domain type:** Shows “You” for your domains, “Competitor” for tracked competitor domains, or automatic classification (Editorial, Corporate, UGC, Reference, Institutional, Other).
  * Click on **All Domain Types** to narrow your analysis to any of the domain types. You can select just one or multiple.
* **Retrieved:** Percentage of chats where a domain appeared as a source.
* **Retrieval rate:** Average of how many times a domain’s URLs were retrieved per chat.
* **Cited:** Measures the percentage of chats where a source is cited at least once. Each chat counts once, regardless of how many times the source is cited within it.
* **Citation share:** Measures the percentage of all citations that belong to a source. If the same source is cited multiple times in one chat, each citation is counted.
* **Citation rate**: Average number of times the domain was explicitly cited when used in your selected time period.
* **Total citations:** The total number of times this URL was cited across all responses in your selected filters and time period.
* **Gap Analysis toggle:** Content gaps and opportunities based on the **Gap Score** column.

<Info>
  **Gap Analysis:** Higher scores highlight bigger opportunities. Sources that appear frequently and mention multiple competitors are often the strongest opportunities to focus on.<br /><br />**Cited** percentages across sources do not add up to 100% because a single chat can cite multiple sources. **Citation share** does add up to 100% because each individual citation belongs to one source.
</Info>

**Domain type**: Provides a high-level classification of the entire domain or website, helping you quickly understand what kind of source it is.

| **Class** | **Description** |
| :- | :- |
| **CORPORATE** | Official company websites and corporate pages. |
| **EDITORIAL** | News sites, blogs, online magazines, and other publications. |
| **INSTITUTIONAL** | Government, educational, and non-profit organization websites. |
| **UGC** | User-Generated Content from social media, forums, and communities. |
| **REFERENCE** | Encyclopedias, documentation, and other reference materials. |
| **COMPETITOR** | Websites and content from direct competitors. |
| **OTHER** | Miscellaneous or uncategorized sources. |

### Changing domain classification

Peec AI automatically classifies every domain and URL it tracks using the categories above. However, these classifications may not always match how you categorize sources. For example, a domain Peec classifies as **Editorial** might be an important partner for your business.

With **custom classifications**, you can apply your own labels to domains and URLs to organize them in a way that better reflects your needs.

You can override a domain’s classification at any time:

1. Find the domain in the **Domain table**.
2. Click its current classification, such as **Reference** or **Editorial**.
3. Search for an existing classification, including any custom ones you’ve created, or create a new one directly from the picker.
4. Your change is saved immediately and applied wherever that source appears in Peec.

<img alt="Changingdomain" />

<Info>
  Manually overridden classifications are clearly marked, so you can easily distinguish them from Peec’s automatic classifications. You can also reset an override at any time to restore the original classification.
</Info>

## Domain metrics

In the domain table, you will see key metrics such as **Retrieved**, **Retrieval Rate**, **Total Citations**, **Cited,** **Citation Share,** and **Citation Rate**. They all give you an idea of how relevant a source is for LLMs, but differ in their influence.

### Retrieved

Retrieved measures the percentage of chats in which one or more URLs from a specific domain appeared in the AI’s answer as a source. This metric indicates whether your or your competitors’ content is being picked up by AI models, demonstrating your domain’s reach even when not explicitly cited.

Retrieved is calculated over your selected time span as:

`Retrieved (Domains) = (Chats with at least one domain URL retrieved / Total chats) × 100`

For example:

* If AI models used any URL from your domain as a source in 40 of 100 chats, then the retrieved percentage would be 40% (40 ÷ 100 × 100 = 40%).

This means that your domain appeared as a source in 40% of all chats, regardless of how many times it was cited in the AI responses.

### Retrieval rate

The Retrieval rate measures the average number of URLs from a domain that AI retrieves per chat. A value above **1.0** means AI typically retrieves multiple pages from that domain in the same chat. This helps show how heavily AI relies on a domain, rather than simply whether it appears as a source.

A brand with a high retrieval rate is deeply embedded in AI responses, not just occasionally present.

<Info>
  A single chat can retrieve multiple URLs from the same domain.
</Info>

Retrieval rate is calculated over your selected timespan as:

`Retrieval Rate = Number of unique URLs retrieved from a domain / total chats`

For example:

* Across the same 100 chats, your domain URLs were retrieved 80 times as a source, yielding a **retrieval rate of 0.8** (80/100).

This means that in chats where your domain was used as a source, the AI pulled an average of 0.8 different pages (URLs) from it. Indicating reliance, not just a one-off mention.

### Total citations

Total citations is the total number of times a domain's URLs were cited across AI responses in the selected date range and filters. Unlike citation rate, which measures the average citations per response, total citations measures overall citation volume. Domains that appear across more chats will rank higher, even if they're cited less often in each individual response.

Total citations are calculated over your selected filters and time span as:

`Total citations (Domain) = Sum of all inline citations of that domain's URLs across responses in your filters`

For example:

* If your domain is cited 60 times across all AI responses in the selected period, your Total citations is 60, regardless of how those citations are distributed across all chats.

This tells you how much total citation volume a domain earned across your tracked prompts, regardless of how many separate responses it came from.

### Cited

**Cited** is the percentage of chats that cite a domain at least once within the selected date range and filters. It compares the number of chats that cite the domain to the total number of chats in the current view. Each chat is counted only once, even if the domain is cited multiple times within the same response.

Cited is calculated over your selected filters and time span as:

`Cited (Domain) = (Chats citing that Domain / Total chats in the current view) × 100`

For example:

* If there are 100 chats in the current view and your domain is cited in 20 of them, your Cited rate is 20% (20 ÷ 100 × 100 = 20%).

Even if your domain is cited several times within those 20 chats, the Cited rate remains 20% because each chat is counted only once.

### Citation share

Citation share is the percentage of all citations that belong to a domain within the selected date range and filters. It compares a domain's Total citations to the total citations across every matching domain, showing how much of the overall citation landscape it accounts for. This makes it easy to see which sources dominate AI citations for the prompts, models, and time period you're analyzing.

Citation share is calculated over your selected filters and time span as:

`Citation share (Domain) = (Total citations of that Domain / Total citations across all domains in the current view) × 100`

For example:

* If your domain was cited 60 times, and all domains in the current view were cited 1,200 times together, your Citation share is 5% (60÷1,200 × 100 = 5%).

This means the domain accounts for 5% of every citation happening across your tracked sources in the current view, a quick read on how much of the citation landscape it owns.

### **Citation rate**

Citation rate is the average number of times a source is explicitly cited in AI responses. A higher rate means the source tends to be referenced multiple times when it appears, indicating that its content is particularly relevant to the topic.

The citation rate is calculated over your selected timespan as:

`Citation Rate (Domain) = Total citations of that Domain / Total responses where Domain was used as a source`

Here "total responses where the domain was used as a source" means the number of **distinct responses** that retrieved the domain (the `retrieved_chat_count` field). This is **not** the `retrieval_count` field: `retrieval_count` counts each distinct URL retrieved from the domain, and because a single response can pull several URLs from the same domain, it can exceed the number of responses. Dividing citations by `retrieval_count` instead yields the deprecated `citation_avg` (a per-retrieval average), not the citation rate.

For example:

* If your domain was used as a source in 40 AI responses, and from those responses, the content from your domain was cited a total of 60 times, a citation rate of 1.5 (60 / 40)

Meaning that every time your domain is used as a source, the AI cites its content an average of 1.5 times per response, suggesting high content authority and consistency.

## Bookmarked domains

Within Peec AI, you can bookmark domains to create a personalized watchlist of the sources you want to monitor closely. This could include key competitors, your own domains, target publications for outreach, or any other sites that matter to you.

**To bookmark a source**, click the **bookmark icon** in the left column of any source row. The source will then appear under the **Bookmarked** tab for easy access.

<img alt="Bookmarked" />

You can quickly switch between **Bookmarked** and **Non-bookmarked** sources, making it easy to focus on your priority domains without scrolling through the full list.


# Identifying your competitors
Source: https://docs.peec.ai/identifying-your-competitors

Track how you perform against competitors and see which brands AI recommends alongside or instead of yours.

<iframe title="YouTube video player" />

[Watch "Identifying your competitors" on YouTube](https://youtu.be/sS9tgmX1naw)

Competitor tracking helps you understand your market position and set realistic targets for improving your AI visibility. This section covers competitor setup and advanced configuration for precise brand detection.

## Why competitors matter

Competitors give you a benchmark for your AI visibility and help put your performance into context. For example, 15% visibility becomes more meaningful when a competitor reaches 45% for the same prompts. This helps you understand the size of the opportunity and what level of visibility is achievable in your market.

Adding competitor brands helps you:

* **Set realistic benchmarks:** See what level of visibility competitors are achieving in your industry.
* **Define ambition levels:** Set clear goals based on how you want to perform against competitors.
* **Identify opportunities:** Find prompts where competitors consistently outperform your brand.
* **Track market shifts:** See when new competitors gain traction or established brands start losing visibility.

## Set up competitors

Go to **Settings** in the sidebar, then select **Brands** under **Project settings**. From there, you can add competitors using automatic suggestions or enter them manually.

### Accept competitor brand suggestions

We detect brands mentioned alongside yours and suggest them when they appear at least twice. On the right of the **Brands** page, you’ll see **Suggested** **Brands:**

* Each suggestion shows **mention count** across your prompts.
* **Track:** Click to add as a tracked competitor.
* **Reject:** Click to dismiss if not relevant.

### Manually add competitors

How to add:

* Click **Add Brand** button in the top-right.
* Enter **Display Name**. This is how the brand will appear in your dashboard and is not used to count brand mentions.
* Add **Tracked Name**. This is the term Peec AI uses to identify and count brand mentions in AI responses. The tracked name and any aliases you add are used for matching and count toward your Visibility percentage.
* Add the brand’s **Domain** if you want to track its website.
* Add a **Regular Expression** if you need more advanced pattern matching.
* Click **Create** to save.

## Manage Competitors

After adding competitors, you can update their settings to make sure they’re tracked accurately. Click any competitor to open their **Brand detail page**, or go to **Brands** from the sidebar. You can manage these settings for your own brand as well.

### Brand detail page

You can update the following settings for any tracked brand:

* **Display Name:** How the brand appears across your dashboards and analysis. Changing this does not affect how brand mentions are tracked.
* **Tracked Name:** The term Peec AI uses to identify and count brand mentions in AI responses. Use the shortest, unique version of the brand name that AI models typically use. **This is not case-sensitive.**
* **Aliases:** Alternative spellings, abbreviations, or variations that should also be identified and counted as mentions of the brand.
* **Advanced: Regular Expression:** Set custom patterns for more complex brand matching when the tracked name and aliases aren’t enough. **This is case-sensitive.**
* **Domain:** The website domain used to classify sources as **You** or **Competitor**. Add alternative domains if the brand uses multiple websites; you can also add subdomains.
* **Color:** Choose a custom color to make the brand easier to identify across graphs and dashboards. You’ll find the color picker next to the brand’s logo.

<Info>
  Saving your changes triggers a data update while Peec searches your existing chats using the updated information. This may take a few minutes to complete.
</Info>

### Control what counts as a brand mention

Use the tracked name, aliases, and RegEx fields to control what Peec considers a valid brand mention.

### **Tracked names**

Use the shortest, unique version of the brand name that people and AI models typically use. For example, use “BMW” instead of “BMW Deutschland,” “HubSpot” instead of “HubSpot, Inc.,” or “Slack” instead of “Slack Technologies.” Focus on how the brand is commonly referred to rather than its official company name.

### **Adding aliases**

Review recent chats to see how AI models refer to the brand, then add any common abbreviations, alternative spellings, or name variations as aliases. This helps ensure those variations are also identified and counted as brand mentions.

### **Advanced RegEx**

Use RegEx for complex cases. Some brands need advanced pattern matching:

* Dictionary words like "Apple" or "Orange" that appear in non-brand contexts.
* Case sensitivity to distinguish "US" (country) from "us" (pronoun).
* Context requirements for specific sentence positions.

<Info>
  Simple RegEx examples:

  * `(Apple|APPLE)` → Match only capitalized versions.
  * `(Apple\\s)` → Match the complete word "Apple", not part of "pineapple."
</Info>


# Welcome to Peec AI
Source: https://docs.peec.ai/intro-to-peec-ai

The #1 AI search analytics tool for marketing teams and agencies.

<iframe title="YouTube video player" />

[Watch "Welcome to Peec AI" on YouTube](https://youtu.be/FfF7rCUayEc)

Your audience isn't just using Google anymore. They're asking ChatGPT or Gemini for product recommendations, using Perplexity for research, getting answers from Claude, and using AI Mode to learn about topics and compare options.

People are having conversations with AI instead of searching with keywords. This means visibility works differently now.

**Peec AI shows you how your brand appears in AI search, and what you can do to influence your visibility.**

## What you'll find in these docs

* **Get started:** You'll get actionable insights about your AI visibility within your first week. First, you'll understand exactly what Peec AI tracks and how it differs from traditional search. Then the quickstart guide walks you through your first setup, from creating prompts that mirror the real questions users ask AI to identifying the right competitors and understanding your first results.
* **Set up your project:** Learn how to craft effective prompts for your industry, organize your tracking system with tags and topics, and identify which competitors to watch. This is where you build everything you need to start collecting meaningful data.
* **Interpret your results:** Once your prompts are running, you'll see visibility data, position trends, and sentiment patterns. This section shows you how to analyze your data to spot real opportunities, from understanding chat details to reading graph trends over time.
* **Take action:** Based on your visibility data, Peec AI generates specific suggestions to improve your results, like recommending which publications to reach out to, identifying content gaps to fill, or highlighting sources where a mention could boost your visibility.
* **Miscellaneous:** Quick access to video walkthroughs, metric definitions, and navigation guides. If you just need a fast answer or want to see a process in action, start here.

## What Peec AI does

Peec AI tracks how your brand appears when people ask AI platforms questions about your industry. Instead of traditional search rankings, it measures three things that matter in AI search: how visible your brand is, what position you appear in when mentioned, and how positively you're described.

* **Visibility**: Shows how often your brand gets mentioned across AI responses; think of it like market share in AI conversations.
* **Position**: Measures where you rank when you do appear, compared with other brands.
* **Sentiment**: Captures whether AI describes your brand positively, neutrally, or negatively when it mentions you.

<Info>
  Read more about the three main metrics, [Visibility](https://docs.peec.ai/metrics/brand-metrics/visibility), [Sentiment](https://docs.peec.ai/metrics/brand-metrics/sentiment) and [Position](https://docs.peec.ai/metrics/brand-metrics/position).
</Info>

The basis for all these metrics is **Sources**: the websites, articles, and other content that AI models reference when they mention brands.

When you see changes in your visibility or position, it's often because new sources have started mentioning you, or existing sources have changed how they talk about your category. Sources are your best opportunity for improvement, because they influence how AI models respond.

## How Peec AI collects data

Peec AI runs your prompts across AI platforms like ChatGPT, Gemini, and Copilot daily, then analyzes patterns over time, since AI responses naturally vary day to day.

These prompts are conversational questions like "What's the best CRM for marketing agencies under 50 people?" instead of keywords like "CRM software." This matches how people actually converse with AI tools.

Unlike traditional analytics tools that rely on APIs, **Peec AI uses UI scraping technology** to interact with AI platforms exactly as real users do. This approach has several advantages:

* **Authentic user experience:** Peec AI interacts with AI platforms through their web interfaces, capturing the same responses users see.
* **Real-world accuracy:** The data reflects actual user experiences, not sanitized API responses.
* **Comprehensive coverage:** Peec AI can reach platforms that don't offer public APIs or have limited API functionality.

<Info>
  Peec AI's UI scraping simulates real user interactions, so the data it collects matches what the average user sees on these AI platforms. For most platforms, this means the platform decides which model to use and whether it runs a web search. This is the reality for a logged-out user, and the approach closest to the average user's experience.
</Info>

## Technical approach: UI scraping vs API access

### **Why we don't use APIs**

Most AI analytics tools rely on official APIs, but that approach has key limitations:

* **Different responses:** API responses often differ from what users see in the actual interface.
* **Different sources:** The number and type of sources in API responses can differ from those shown to real users.

### **Our UI scraping advantage**

Instead of APIs, Peec AI uses browser automation to interact with AI platforms through their web interfaces:

* **Real user simulation:** Peec AI uses the same interfaces your customers use, so the data reflects what real users see.
* **Consistent data quality:** Every interaction follows the same user journey as a real user.
* **Resilient to API changes:** Because Peec AI doesn't depend on official APIs, it keeps working when those APIs change or restrict access.

This approach means your visibility data reflects the real user experience, not a filtered or modified API response.

## How Peec AI helps

Peec AI shows you where you stand in AI search and what you can do about it. You can track your visibility trends over time, spot when competitors gain ground, and identify the specific sources that influence AI responses in your industry.

The analysis goes beyond basic mentions: you can filter by time period, compare multiple competitors, and access all your data through exports, the [Data Studio connector](https://docs.peec.ai/looker/introduction), and the [API](https://docs.peec.ai/api/introduction) for custom analysis or integration with your existing analytics stack.

Peec AI helps you:

* **Track AI visibility:** See when you're mentioned in relevant conversations across different AI models.
* **Monitor competitors:** Understand who else appears in your space, and how often.
* **Find citation opportunities:** Discover which sources AI models trust and reference.
* **Spot content gaps:** Identify when you're cited as a source but not mentioned as a brand.
* **Track trends over time:** Monitor how your visibility changes as AI models evolve or you adapt your strategy.
* **Make data-driven decisions:** Use probability-based insights for your strategy.


# Data Studio connector
Source: https://docs.peec.ai/looker/introduction

Complete guide to connecting and using Peec AI data in Data Studio (formerly known as Looker Studio).

## What is the Peec AI Data Studio connector?

The Peec AI Data Studio community connector lets you import your AI search visibility data directly into [Google Data Studio](https://lookerstudio.google.com/). You can then create custom dashboards and reports using your brand performance data from AI search engines like ChatGPT, Perplexity, and Gemini.

Data Studio is Google’s free data visualization tool that helps you turn your data into informative, easy-to-read, and shareable dashboards and reports.

## How this helps

* **Real-time data access**: Connect directly to your Peec AI project for up-to-date visibility metrics.
* **Custom visualizations**: Create charts, graphs, and tables that match your reporting needs.
* **Team collaboration**: Share dashboards with stakeholders and team members.

## How to set up the connector

Before you begin, ensure you have:

* A Peec AI account with access to at least one project
* A Google account with access to Data Studio

### Create the data source using the Peec connector

1. Use [**this link**](https://datastudio.google.com/datasources/create?connectorId=AKfycbwE9kg7FJQKlF6i4SzB4MZFoK0J0OxJzpoRge0LIEqWwImH2G18KE72-0z-M9zzG7eMTw\&authuser=0) to access Peec AI connector (make sure you’re signed in with your Google account).
2. Create an API key in the Peec dashboard under “API Keys”
   1. When creating the key, select **Scope: Project**
   2. Give the key a name (e.g., “Data Studio Key”)
3. Enter the API key in the empty field placeholder and click on **Next,** and then **Connect**
4. Once it loads, click on **Create Report** and then **Add to report**

<Frame>
  <img alt="Connecting To Looker" />
</Frame>

<Info>
  The Data Studio connector is available only to users with a valid Peec API Key in their account.
</Info>

<Info>
  If you previously had a connection with Data Studio, you can simply follow the same steps, and once the data source is added, you can switch it in the report.
</Info>

## Available data fields

The Peec AI connector provides the following data fields:

### Dimensions

| **Name** | **Display Name** | **Description** |
| :- | :- | :- |
| brand | Brand | The brands that you have in Peec |
| country\_code | Country Code | The country code (two letter ISO code) |
| date | Date | The date (year month and day) as an integer |
| model | Model | The AI models that you have in Peec |
| model\_channel\_id | Model Channel | The model channel (e.g. ChatGPT UI, OpenAI API) used to generate the chats |
| prompt | Prompt | The prompt text used to generate the chats that you have in Peec |
| source\_domain | Domain | The domain of the source URL |
| source\_domain\_classification | Domain Classification | The classification of the source domain |
| source\_url | URL | The source URL of the sources found in the chats |
| source\_url\_classification | URL Classification | The classification of the source URL |
| tag | Tag | The tags you have created for the project in Peec |
| topic | Topic | The topics you have created for the project in Peec |
| workspace | Project | The project that the data belongs to |

### Metrics

| **Name** | **Display Name** | **Description** |
| :- | :- | :- |
| citation | Citation | The number of times a source URL is cited in the chats |
| retrieval | Retrieval | The number of unique chats where a source URL was retrieved |
| retrieval\_percentage | Retrieval Percentage | The percentage of total chats where a source URL was retrieved |
| visibility | Visibility | The number of chats where a brand was mentioned at least once |
| sentiment | Sentiment | The sentiment of a brand in chats |
| position | Position | The position of a brand in chats |
| usage | Usage | The number of times a source URL is used in chats |
| sov | Share of Voice | The percentage of total mentions that belong to a brand |

## Creating your first report

<iframe title="YouTube video player" />

[Watch "Creating Engaging Reports with Looker Studio 📊" on YouTube](https://youtu.be/fFn4fVEQhb8)

### Step 1: Create a new report

1. After configuring your data source, click **CREATE REPORT**.
2. Data Studio will open the report editor with your Peec AI data source connected.

### Step 2: Add visualizations

Data Studio offers a wide range of charts and tables to fit your needs. Have a look at the

[Types of Charts in Data Studio ](https://cloud.google.com/looker/docs/studio/types-of-charts-in-looker-studio)for more options.

### Step 3: Apply filters and controls

Add interactive controls to make your reports dynamic.

### Getting help

If you encounter issues not covered here:

**Contact support**: Email [**support@peec.ai**](mailto:support@peec.ai) with:

* Description of the issue
* Screenshots if applicable


# Manage your project
Source: https://docs.peec.ai/manage-your-project



<iframe title="YouTube video player" />

[Watch "Managing your project for brands" on YouTube](https://youtu.be/2bJ9OZy2-cE)

Everything related to your projects can be managed under **Settings → Projects** under the **Company** section. Here, you can view your existing projects, update their tracking setup, including prompts, models, and project names, or delete projects when needed.

In the **Projects** tab, you’ll see:

* The number of prompts allocated to your projects and the maximum available on your subscription.
* The total number of prompts currently being tracked across all projects.
* A list of your projects, including the number of prompts and models being tracked and their tracking frequency.

## Updating your project

You can adjust the prompt limit, change how many models you track, or delete a project, all from the same tab.

### Adjusting prompts

Adjust how many prompts each project tracks from the project table by:

* Locate the project you want to adjust.
* Click the box in the "Used / Allocated Prompts" column.
* Enter a new value within your prompt limit.
* Click anywhere else on the screen to save.

Your pool of allocated prompts adjusts automatically as you increase or reduce the number of prompts per project.

<img alt="Promptsallocated" />

### Changing AI models

Choose which AI models to track for each project. While three models are selected by default, you can select or deselect models based on your project’s tracking needs. For example, one project may only need **ChatGPT**, while another may require broader model coverage.

In the projects table:

* Find the project you want to update.
* Click on the **Models** box to open the selector.
* Select or deselect the models you need.
* Click **Update**.

<img alt="Modelselection" />

### Updating your project details

In the Projects tab, you can edit the main details of a project. You can rename it so colleagues recognize it easily, or adjust the location, language, or domain being tracked.

To change the details of your project:

* Click on the three dots in the right column
* Click on **Edit Details** to open the settings
* Click **Update** to save all the changes

<img alt="Editdetails" />

### Exporting chats

To export all chats for a project as a CSV, download it from the Projects tab.

To export all chats:

* Click the three dots in the right column.
* Click **Export chats**.
* Click **Generate export** and wait for it to finish.
* Download the file and use it for your analysis.

<img alt="Export Chats" />

## Pausing your project

Pause a project when you no longer need to track it continuously but want to keep it. You can still review the data and resume later.

When you pause a project, all its prompts stop running, and it stops collecting data until you resume. Any data that would have been collected during the pause can't be recovered, so be sure before pausing. After you resume, prompts start running again, and new data begins to appear.

Allocated prompts no longer count toward your limit and can be reassigned to other projects.

<Info>
  Pausing a project isn't available on Starter plans.
</Info>

To pause a project:

* Click the three dots for the project you want to pause.
* Click **Pause project** and confirm.

To resume it:

* Click the three dots again.
* Click **Resume project**.
* Make sure you have the required prompts available, then click **Resume**.


# MCP Server
Source: https://docs.peec.ai/mcp/introduction

Connect AI assistants like Claude, Cursor, and other MCP-compatible tools directly to your Peec AI data. Ask questions in plain language and get answers from the same data the dashboard shows.

Ask your AI assistant about your brand's AI search visibility and get answers from your actual Peec AI data. This works with Claude, Cursor, VS Code, Windsurf and others.

## What you can do

* **Check brand visibility** across ChatGPT, Perplexity, Gemini, Google AI Overviews, Google AI Mode, Claude, Microsoft Copilot, and Grok
* **Compare against competitors** on the main metrics such as visibility, sentiment, share of voice, and position
* **Analyze sources** to see which domains and URLs AI models retrieve and cite most often, and how that shapes your content strategy
* **Inspect source content** by pulling the scraped markdown of any cited URL to see exactly what an AI engine read
* **Spot trends** by date, AI model, topic, or country to surface patterns and gaps to act on
* **Inspect AI bot traffic** from [Agent Analytics](/crawl-insights): list the bots Peec tracks and aggregate visit counts from your access logs, grouped by bot, response status, host, path, or time bucket
* **Get ranked next steps** from Peec Actions: opportunity-scored recommendations grouped by owned pages, editorial coverage, reference sites, and UGC communities
* **Run ready-made workflows** with built-in [prompts](/mcp/prompts) like the weekly pulse, engine scorecard, topic heatmap, and campaign tracker. One slash command, full report.
* **Manage your project setup** by asking the assistant to create, edit, or delete prompts, topics, tags, tracked brands, and custom domain/URL classifications. Works one at a time or in batches of up to 50. It always confirms before applying a change.
* **Refine your brand profile** so AI-generated prompt suggestions match how you actually describe your business.

## How it works

<Steps>
  <Step title="Connect">
    Add the server URL to your AI tool. See our [setup guide](/mcp/setup) for your platform.
  </Step>

  <Step title="Sign in">
    Authorize with your Peec AI account. This only happens once.
  </Step>

  <Step title="Ask questions or run a prompt">
    Free-form questions:

    * *"How has our brand visibility changed over the last 30 days?"*
    * *"Which competitors have the highest share of voice in ChatGPT?"*
    * *"What are our most cited URLs across AI search engines?"*

    Or pick a built-in [prompt](/mcp/prompts) (slash command) for a ready-made analysis like the weekly visibility pulse or competitor radar.
  </Step>
</Steps>

## Connection details

Your tool may ask for these details:

| Property | Value |
| - | - |
| **Server URL** | `https://api.peec.ai/mcp` |
| **Transport** | Streamable HTTP |
| **Authentication** | OAuth 2.0 or Personal Access Token |

## Authentication

Two options, depending on what your client supports:

* **OAuth 2.0.** Your AI assistant opens a Peec AI consent page in your browser. Sign in and click **Agree & Allow Access**. The session persists across conversations.
* **Personal Access Token.** Create a token under **API Keys → Personal Access Tokens** in [app.peec.ai](https://app.peec.ai/api-keys), then attach it as an `Authorization: Bearer <token>` header on your client's MCP connection. Best for headless setups, CI, or clients without OAuth support.

Tokens act on your user, so every call respects the same project and organization-owner permissions as your dashboard session. See the [setup guide](/mcp/setup) for client-by-client examples.

<Note>
  The consent page shows which application is requesting access. You can switch accounts if needed.
</Note>

## Read and write access

Most tools are read-only. Reports, chat inspection, source content, and actions all pull existing data.

A smaller set of tools edits your project configuration. The assistant uses them when you ask to add a prompt, rename a topic, or update a tracked brand. Every write tool is flagged `readOnlyHint: false`, and delete tools are flagged `destructiveHint: true`, so your client prompts for confirmation before the call runs. Write tools require organization-owner access on the project.

See [tools](/mcp/tools) for the full list.

## Supported platforms

The MCP works with any tool that supports [MCP (Model Context Protocol)](https://modelcontextprotocol.io/). Setup guides:

* Claude (Desktop, Web, Code)
* Cursor
* VS Code (GitHub Copilot)
* Windsurf

See the [setup guide](/mcp/setup).

## Requirements

* A Peec AI account with at least one project
* A supported AI tool

## Support

Stuck? Email [support@peec.ai](mailto:support@peec.ai) or use the chat bubble in the dashboard.

See our [Privacy Policy](https://peec.ai/legal/privacy-policy) for data handling details.


# Prompts
Source: https://docs.peec.ai/mcp/prompts

Peec AI ships native MCP prompts: ready-to-run analysis workflows exposed as slash commands in your AI tool. Each prompt runs a scripted sequence of tool calls and formats the output for you.

Prompts are a built-in MCP primitive. Instead of asking your AI assistant to combine tools step-by-step, you invoke a single slash command and get a fully formatted report back.

<Note>
  Prompts are versioned with the Peec AI MCP server. When we ship a new one, it appears in your client automatically. No install.
</Note>

## How to invoke a prompt

The command surface depends on your client.

| Client | How to invoke |
| - | - |
| Claude (Desktop, Web, Code) | Type `/` in the message input and pick the prompt from the list |
| Cursor | Type `@` in the chat and pick the prompt |
| Other MCP clients | Check your client's documentation for prompt support |

<Tip>
  If prompts don't show up after connecting, remove and re-add the Peec AI integration to refresh the tool and prompt list.
</Tip>

## Available prompts

All prompts take a `project` argument (name or ID). Your AI assistant resolves the name for you, so `"Acme Q2"` works as well as a project ID.

### peec\_weekly\_pulse

**Weekly Visibility Pulse.** Week-over-week digest covering brand metrics, competitor movers, source shifts, and sentiment flags. Formatted for sharing internally.

| Argument | Required | Description |
| - | - | - |
| `project` | Yes | Project name or ID |

Use when: you want a quick Monday-morning snapshot of what changed last week.

***

### peec\_competitor\_radar

**Competitor Movement Radar.** Scans every brand × topic × engine combination for significant shifts. Returns the biggest gainers and losers, hypothesized drivers, and the topics where your own brand is most exposed.

| Argument | Required | Description |
| - | - | - |
| `project` | Yes | Project name or ID |
| `threshold_pp` | No | Minimum percentage-point change to flag (default: `10`) |

Use when: a competitor suddenly seems more visible and you want to know where and on which engines.

***

### peec\_engine\_scorecard

**AI Engine Scorecard.** Per-engine breakdown of brand visibility, share of voice, sentiment, position, plus source retrieval and citation rate from your own domains. Highlights the engine with the most untapped potential.

| Argument | Required | Description |
| - | - | - |
| `project` | Yes | Project name or ID |

Use when: you want to know which AI engine to focus on next.

***

### peec\_topic\_heatmap

**Topic × Model Heatmap.** Visibility heatmap across all your topics and all tracked AI engines, calibrated to your own baseline so cells are labeled as blind spots, weak, moderate, strong, or dominant.

| Argument | Required | Description |
| - | - | - |
| `project` | Yes | Project name or ID |

Use when: you want to find blind spots and strongholds across topics and engines at a glance.

***

### peec\_prompt\_grader

**Prompt Set Grader.** Grades your tracked prompt set on topic balance, tag hygiene, funnel coverage, branded/unbranded segmentation, duplicate detection, and model data gaps. Returns an A-F report card with the top 3 fixes.

| Argument | Required | Description |
| - | - | - |
| `project` | Yes | Project name or ID |

Use when: you suspect your prompt set is skewed, incomplete, or noisy.

***

### peec\_source\_authority

**Source Authority Audit.** How your domains perform as sources across AI engines: retrieval rates, citation rates, top URLs, content type breakdown, and authority gaps where competitors are cited but you are not.

| Argument | Required | Description |
| - | - | - |
| `project` | Yes | Project name or ID |

Use when: you're optimizing content and want to know which URLs and formats get picked up by AI.

***

### peec\_campaign\_tracker

**PR / Campaign Impact Tracker.** Before/after comparison around a launch date. Tracks brand metrics and source pickup, broken down by engine. Pass specific URLs to track a PR push, or omit them to analyze your whole domain.

| Argument | Required | Description |
| - | - | - |
| `project` | Yes | Project name or ID |
| `campaign_date` | Yes | Launch date in `YYYY-MM-DD` format |
| `urls` | No | Comma-separated URLs to track. If omitted, analyzes your own brand domains broadly. |

Use when: you shipped a PR campaign, guest post, or content refresh and want to measure AI impact.

***

### peec\_optimize\_content

**Work Through a Content Optimization.** Works through the suggestions on a content optimization action. It applies the rewrites Peec drafted, writes the content that `edit` suggestions only describe, and reports what changed along with the score before and after. Changes land as tracked edits under your name, which you can revert on the Optimize content screen.

| Argument | Required | Description |
| - | - | - |
| `project` | Yes | Project name or ID |
| `action` | Yes | The content optimization action ID, or the page's URL |
| `instruction` | No | What you want done, e.g. `only the pricing gaps` or `make the intro shorter`. If omitted, it works through every pending suggestion. |

Use when: you want your AI assistant to apply a page's suggestions for you instead of working through them one by one in the workspace.

<Note>
  This prompt only appears when **Content optimization** is enabled for the project. It edits your article, so it needs company member access. See [`edit_optimize_content`](/mcp/tools#edit-optimize-content) and [`resolve_optimize_content_suggestions`](/mcp/tools#resolve-optimize-content-suggestions).
</Note>

## Combining prompts with free-form questions

Prompts are a starting point. After a prompt runs, follow up with questions in plain language. Your AI assistant still has access to every [tool](/mcp/tools), so you can drill into any row, engine, or topic.

> *"Run the weekly pulse, then dig into why Perplexity visibility dropped"*
> *"After the competitor radar, show me the chats from last week that mentioned Acme"*

<Info>
  Prompts are read-only, except `peec_optimize_content`, which edits the article you point it at. They only use the same Peec AI data you can already see in the dashboard.
</Info>


# Setup Guide
Source: https://docs.peec.ai/mcp/setup

Step-by-step instructions for connecting the Peec AI MCP Server to Claude, Cursor, and other AI tools. Stuck? Email support@peec.ai.

## Server URL

All platforms use the same URL:

```text theme={null}
https://api.peec.ai/mcp
```

## Authentication options

The server accepts two auth methods. Pick based on your client.

* **OAuth 2.0** (default for most clients). The first connection redirects you to Peec AI to sign in and approve access. Your session persists across conversations. Use for Claude Desktop, Claude Web, Cursor, VS Code, Windsurf, and any other client that walks through an OAuth consent screen.
* **Personal Access Token (PAT).** A long-lived bearer token tied to your Peec user. Use for clients that don't support OAuth, headless setups, CI, or when you want to keep the token in your own secrets manager.

### Create a Personal Access Token

<Steps>
  <Step title="Open API Keys">
    Sign in to [app.peec.ai](https://app.peec.ai) and go to **API Keys** in the sidebar.
  </Step>

  <Step title="Create a token">
    In the **Personal Access Tokens** section click **Create token**. Give it a name (e.g. `Claude Desktop`, `Cursor laptop`) and pick an expiration: **Never**, **30 days**, **60 days**, or **90 days**.
  </Step>

  <Step title="Copy the token">
    Copy the token immediately. It's shown only once. Treat it like a password — anyone with it can act as you in Peec via MCP.
  </Step>
</Steps>

Tokens act on your user, so every call respects the same project access and organization-owner checks as your dashboard session. The **Last Used** column on the API Keys page updates each time the token is used, so you can spot tokens you can safely revoke. Revoke a token any time from the same page; clients using it lose access immediately.

## Claude Desktop and Web (claude.ai)

<Steps>
  <Step title="Open settings">
    Open Claude Desktop and go to **Settings** or \*\*Customize \*\*(gear icon), then **Connectors**.
  </Step>

  <Step title="Browse connector">
    Search for and click on the **Peec AI** connector and install it
  </Step>

  <Step title="Authorize">
    Click **Connect**. You'll be redirected to Peec AI to sign in. Once authorized, return to the Claude Desktop.

    <Info>
      Please note that only workspace Admins in Claude can add the connector. If you are not able to, you might want to check with your admin
    </Info>

    <Frame>
      <img alt="Connecting Claude MCP" />
    </Frame>
  </Step>
</Steps>

## Claude Code (CLI)

OAuth (default):

```bash theme={null}
claude mcp add peec-ai --transport http https://api.peec.ai/mcp
```

Claude Code will prompt you to authorize when you first use a Peec AI tool.

With a Personal Access Token:

```bash theme={null}
claude mcp add peec-ai --transport http https://api.peec.ai/mcp \
  --header "Authorization: Bearer YOUR_PEEC_PAT"
```

## ChatGPT

Peec AI is available in the ChatGPT plugin directory, so there's no server URL to enter and no developer mode required.

<Steps>
  <Step title="Open the plugin directory">
    In ChatGPT, open **Plugins** from the sidebar, or go to [chatgpt.com/plugins](https://chatgpt.com/plugins). Some accounts show this as **Settings → Apps & connectors**.
  </Step>

  <Step title="Install Peec AI">
    Search for **Peec AI** and click **Install**.

    <img alt="Chatgpt" />
  </Step>

  <Step title="Authorize">
    Click **Connect**. You'll be redirected to Peec AI to sign in and approve access. Once authorized, return to ChatGPT.

    <Info>
      On Enterprise and Edu workspaces, an admin may control plugin access by role. If Peec AI doesn't appear in the directory, ask your workspace admin to check the installation policy under **Workspace settings → Plugins**.
    </Info>
  </Step>

  <Step title="Use it in a chat">
    Start a new conversation and mention the plugin with `@Peec AI`, or select it from **Plugins**. Installed plugins are also available in Codex.
  </Step>
</Steps>

## Codex (CLI and IDE)

OAuth (default). Add the server to `~/.codex/config.toml`:

```toml theme={null}
[mcp_servers.peec-ai]
url = "https://api.peec.ai/mcp"
```

Then run `codex mcp login peec-ai` to authorize. Use `/mcp` in the Codex TUI to confirm the connection.

With a Personal Access Token:

```toml theme={null}
[mcp_servers.peec-ai]
url = "https://api.peec.ai/mcp"
bearer_token_env_var = "YOUR_PEEC_PAT"
```

## Cursor

<Steps>
  <Step title="Open MCP settings">
    Open **Cursor Settings**, then go to **Tools & Integrations**, then **MCP**.
  </Step>

  <Step title="Add server">
    Click **Add Custom MCP** and enter the server URL:

    ```text theme={null}
    https://api.peec.ai/mcp
    ```

    Select **Streamable HTTP** as the transport type. To use a PAT instead of OAuth, add an `Authorization: Bearer YOUR_PEEC_PAT` header on the connection.
  </Step>

  <Step title="Authorize">
    Without a PAT, you'll be prompted to sign in via Peec AI when you first use the server.
  </Step>
</Steps>

## VS Code (GitHub Copilot)

Add a `.vscode/mcp.json` file to your workspace (or open the user-level config via the **MCP: Open User Configuration** command):

```json theme={null}
{
  "servers": {
    "peec-ai": {
      "type": "http",
      "url": "https://api.peec.ai/mcp"
    }
  }
}
```

To authenticate with a Personal Access Token instead of OAuth, add a header:

```json theme={null}
{
  "servers": {
    "peec-ai": {
      "type": "http",
      "url": "https://api.peec.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PEEC_PAT"
      }
    }
  }
}
```

## Windsurf

<Steps>
  <Step title="Open MCP settings">
    Open **Windsurf Settings**, then go to **MCP**.
  </Step>

  <Step title="Add server">
    Click **Add Server** and enter the server URL:

    ```text theme={null}
    https://api.peec.ai/mcp
    ```
  </Step>

  <Step title="Authorize">
    You'll be prompted to sign in via Peec AI when you first use the server.
  </Step>
</Steps>

## Other platforms

The Peec AI MCP Server uses Streamable HTTP transport and works with any AI tool that supports the MCP standard. Use the server URL `https://api.peec.ai/mcp` and configure your tool's MCP settings accordingly. If the client doesn't support OAuth, attach a Personal Access Token as an `Authorization: Bearer <token>` header.

## Verify your connection

After setup, try asking your AI assistant:

> *"List my Peec AI projects"*

You should see a list of projects your account has access to. If that works, you're all set. From here:

* Run a built-in [prompt](/mcp/prompts) (slash command) for a ready-made analysis like the weekly visibility pulse or competitor radar.
* Or browse the [use cases](/mcp/use-cases) for free-form question ideas.

## Troubleshooting

**"Authorization failed" or "Unauthorized"**

* Check that you signed in with the correct Peec AI account
* Try removing and re-adding the integration
* Clear your browser cookies for `api.peec.ai` and try again
* Using a PAT? Confirm the token isn't expired or revoked in **API Keys → Personal Access Tokens**, and that the `Authorization: Bearer ...` header is being sent.

**"No projects found"**

* Make sure your account has access to at least one project in the [Peec AI dashboard](https://app.peec.ai)

**Connection timeout**

* Check your internet connection
* Make sure the URL is exactly `https://api.peec.ai/mcp`

**Need help?** Email us at [support@peec.ai](mailto:support@peec.ai).


# Tools Reference
Source: https://docs.peec.ai/mcp/tools

Every tool the Peec AI MCP Server exposes, with parameters and response fields.

The Peec AI MCP Server exposes two sets of tools:

### **Read tools** (51) return data:

* Projects, brands, model channels
* Prompts and prompt suggestions
* Chats and chat reports
* Brand/domain/URL reports
* Actions
* Content optimization articles and suggestions
* Brand perception attributes and objections
* Fact-checking facts
* Scraped source content
* Custom classifications
* The Brand Profile
* Products, merchants and the shopping catalog
* Shopping performance/demand/trend metrics
* The Peec documentation
* AI referral traffic
* Agent Analytics (known bots and access-log visit counts)

### **Write tools** (48) create, update, archive, or delete:

* Projects
* Brands, prompts, tags, tag groups, topics
* Products, categories, facts
* Custom domain/URL classifications
* Attribute clusters
* Actions (write your own, edit any action, update statuses and steps)
* Content optimization articles (rewrite passages, apply or dismiss suggestions)
* The Brand Profile
* Generate topics and prompt suggestions

Your AI assistant calls these tools automatically based on your questions. You don't need to invoke them directly, but this reference helps you understand what is available.

A few tools are only available when the feature behind them is enabled for your project:

* Fact tools → **Fact-checking**
* `get_optimize_content`, `edit_optimize_content`, and `resolve_optimize_content_suggestions` → **Content optimization**. The other action tools are always available, but they return `CONTENT_OPTIMISATION` actions only when it's enabled.
* `get_ai_referrals` → **My website**

A Company Member can turn these on under **Settings → Company Settings → Early access**.

Until a feature is enabled, your assistant doesn't see its tools at all. Calling one by name will return **"tool not found"**.

<Note>
  All tools except `list_projects`, `create_projects`, `search_docs`, `read_doc`, and `list_referral_sources` require a `project_id`. Your AI assistant handles this automatically after you pick a project.

  Write tools require company member access on the project. Any project member can use the read tools.

  Tool calls are rate limited to 1,000 calls per minute per user. If you hit the limit, the server tells your assistant to retry after a few seconds.
</Note>

## Response format

Most tools return compact **columnar JSON**:

```json theme={null}
{
  "columns": ["brand_id", "brand_name", "visibility", "..."],
  "rows": [
    ["b_1", "Acme", 0.42, "..."],
    ["b_2", "Contoso", 0.18, "..."]
  ],
  "rowCount": 2
}
```

Each row is an array of values matching the `columns` order. List tools (`list_brands`, `list_topics`, `list_tags`, `list_prompts`, `list_chats`, `list_search_queries`, `list_shopping_queries`, `list_products`, `list_categories`, `list_global_brands`, `list_shopping_demand`, `list_shopping_performance`, `list_domain_classifications`, `list_url_classifications`) also return a `totalCount` field with the total matching records across pages, so you can tell whether to paginate. `get_chat`, `get_url_content`, `get_project_profile`, `get_product`, `get_shopping_trend`, `get_shopping_attributes`, `read_doc`, `list_bots`, and `get_agent_visits` are exceptions: they return their object directly.

## list\_projects

Lists all projects your account has access to. This is always called first.

**Columns:** `id`, `name`, `status`

***

## list\_brands

List brands (your brand and tracked competitors) in a project.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `limit` | number | No | Max results (default: 100) |
| `offset` | number | No | Results to skip (default: 0) |
| `fields` | string\[] | No | Columns to return. Omit for all of them. |

**Columns:** `id`, `name`, `domains`, `aliases`, `is_own`, `regex`, `color`, `source`

`aliases` are alternate names the brand is matched under. `is_own` indicates whether this is your brand (`true`) or a competitor (`false`). A nonempty `regex` overrides name and alias matching; `null` means none is set.

`color` is the brand's hex color, or `null` when none is set and Peec shows an automatic one. `source` is how the brand was added: `onboarding` for competitors Peec suggested when the project was created, `suggestion` for a brand suggestion someone accepted, and `manual` for a brand created in the app, through the API, or through MCP. `null` means the brand was added before Peec recorded this.

***

## list\_topics

Lists topic groupings in a project. Each prompt belongs to one topic.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `limit` | number | No | Max results (default: 100) |
| `offset` | number | No | Results to skip (default: 0) |

**Columns:** `id`, `name`

***

## list\_tags

Lists tags (cross-cutting labels) in a project.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `group` | string | No | Filter to tags in this user-defined group |
| `limit` | number | No | Max results (default: 100) |
| `offset` | number | No | Results to skip (default: 0) |

**Columns:** `id`, `name`, `is_system`, `group`

System tags (`is_system: true`) are Peec-managed branding/intent tags; their `group` is `branding` or `intentType`. User tags carry their user-defined group name in `group` (or `null` when ungrouped). Use [`list_tag_groups`](#list-tag-groups) to enumerate the user-defined groups.

***

## list\_tag\_groups

Lists the user-defined tag groups in a project, each with its shared color and tag count. System groups (branding/intentType) are not included — see [`list_tags`](#list-tags).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |

**Returns:** `{ data: [{ group, color, tag_count }] }`.

***

## list\_models

Lists all AI engines (models) configured for a project. Use this to resolve model names (e.g. "ChatGPT", "Perplexity") to IDs before filtering reports, and to label model IDs with human-readable names when presenting results.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |

**Columns:** `id`, `name`, `is_active`

The `is_active` field indicates whether the model is enabled for this project. Inactive models return empty data in reports.

<Note>
  Filtering and breaking down reports by `model_id` is deprecated. Prefer `model_channel_id` (see [`list_model_channels`](#list-model-channels)) — channels are stable engine identifiers that survive model version upgrades.
</Note>

***

## list\_model\_channels

Lists the AI engine channels tracked by Peec. A **model channel** is a stable identifier for an engine (e.g. `openai-0` = ChatGPT UI) that persists as the underlying model is upgraded. Use it to filter or break down reports without tying yourself to a specific model version.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |

**Columns:** `id`, `description`, `current_model_id`, `is_active`, `unsupported_country_codes`

* `current_model_id` is the model ID currently active in the channel. Pass this as `model_id` if a report still requires the deprecated filter.
* `is_active` mirrors the engine's status for this project. Inactive channels return empty data.
* `unsupported_country_codes` lists ISO 3166-1 alpha-2 codes the channel can't serve. Chats requested for those countries are not created.

***

## list\_prompts

Lists prompts in a project. You can filter by topic or tag.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `topic_id` | string | No | Filter by topic ID |
| `tag_id` | string | No | Filter by tag ID |
| `limit` | number | No | Max results (default: 100) |
| `offset` | number | No | Results to skip (default: 0) |

**Columns:** `id`, `text`, `tag_ids`, `topic_id`, `volume`

`tag_ids` is an array of tag IDs. `topic_id` is the topic ID or `null`. `volume` is a relative search-volume bucket: `very low`, `low`, `medium`, `high`, `very high`, or `null` when the prompt does not have a volume signal yet.

***

## list\_prompt\_suggestions

Lists the prompts Prompt discovery generated and left awaiting review. A suggestion isn't tracked and produces no data until you accept it, so this is the review queue rather than part of your prompt set. Filter by `topic_id` to work through one topic at a time.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `topic_id` | string | No | Only suggestions on this topic |
| `fields` | string\[] | No | Columns to return. Omit for all of them. |
| `limit` | number | No | Max results (default: 100, max: 1000) |
| `offset` | number | No | Results to skip (default: 0) |

**Columns:** `id`, `text`, `topic_id`, `tag_ids`, `country`, `volume`

| Field | Description |
| - | - |
| `id` | Prefixed `pr_`. A suggestion keeps its ID when accepted, so the tracked prompt is findable under the same ID with [`list_prompts`](#list-prompts). |
| `tag_ids` | Tag IDs. Resolve the names with [`list_tags`](#list-tags). |
| `country` | The market the suggestion was generated for |
| `volume` | Relative search volume, or `null` when it isn't available |

Accept or reject them with [`finalize_prompt_suggestions`](#finalize-prompt-suggestions), or edit one first with [`update_prompt_suggestions`](#update-prompt-suggestions).

***

## get\_prompt\_suggestion\_generation

Reads the status of a generation run started by [`generate_prompt_suggestions`](#generate-prompt-suggestions). `QUEUED` and `RUNNING` mean it's still working. `SUCCEEDED` and `FAILED` are final, and a successful run can still produce zero suggestions.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `generation_id` | string | Yes | The generation ID returned by `generate_prompt_suggestions` |

Once a run succeeds, read what it produced with [`list_prompt_suggestions`](#list-prompt-suggestions).

***

## list\_chats

List individual AI responses (chats) for a project over a date range. Each chat is one prompt run against one AI engine on a given date. Combine with `get_chat` to inspect the full response.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `start_date` | string | Yes | Start date (YYYY-MM-DD) |
| `end_date` | string | Yes | End date (YYYY-MM-DD) |
| `brand_id` | string | No | Only chats that mentioned this brand |
| `prompt_id` | string | No | Only chats produced by this prompt |
| `model_id` | string | No | Only chats from this AI engine. **Deprecated** — prefer `model_channel_id`. Ignored if `model_channel_id` is also provided. |
| `model_channel_id` | string | No | Only chats from this stable engine channel |
| `features` | string\[] | No | Only chats whose response contains all of the given features. Values: `SHOPPING`, `PRODUCT_COMPARISON`, `AD`, `MAP`, `WEB_SEARCH`. Multiple values are AND'd (a chat must contain every listed feature to match). |
| `include_archived_prompts` | boolean | No | Include chats whose prompt has been archived. Default `false`. Set to `true` only when historical chats for prompts that are no longer active are needed. Chats for deleted prompts are always excluded regardless of this flag. |
| `limit` | number | No | Max results (default: 100, max: 10000) |
| `offset` | number | No | Results to skip (default: 0) |

**Columns:** `id`, `prompt_id`, `model_id`, `model_channel_id`, `date`, `features`

`features` is an array of feature flags marking special elements detected in the assistant response. Use the same values listed under the `features` filter above.

By default, chats are excluded if their prompt has been deleted or archived. Pass `include_archived_prompts=true` to include chats for archived prompts (e.g. for a historical lookback against a prompt no longer being tracked). Chats for deleted prompts are always excluded.

***

## get\_chat

Get the full content of a single chat: the user prompt, the AI response, every source URL the model retrieved, every brand it mentioned, every search query it issued, and any extracted products.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `chat_id` | string | Yes | The chat ID (from `list_chats`) |

**Returns:**

| Field | Description |
| - | - |
| `messages` | The user prompt and assistant response(s) |
| `brands_mentioned` | Brands detected in the response with their position |
| `sources` | URLs the model retrieved, with citation counts and position |
| `queries` | Search queries the model issued |
| `products` | Product gallery entries extracted from the response |
| `features` | Feature flags for special elements detected in the assistant response. Values: `SHOPPING`, `PRODUCT_COMPARISON`, `AD`, `MAP`, `WEB_SEARCH`. |
| `maps` | Local-business map cards (one per business pinned in a map widget). Each entry: `{ name, url? }`, where `url` is the Google Maps directions deeplink. |
| `ads` | Paid ad placements rendered by the model. Each entry: `{ brandName, url, id?, adUnitType?, adsRequestId?, cards }`, where `cards` is an array of `{ title?, body?, imageUrl?, targetUrl? }`. `targetUrl` is the clickout URL with attribution UTM params. |
| `prompt` | `{id}` |
| `model` | `{id}` — **Deprecated**, prefer `model_channel` |
| `model_channel` | `{id}` — stable engine channel ID (e.g. `openai-0`) |

***

## get\_chats\_report

Aggregate counts and rich-answer shares across a project's chats over a date range. Reach for it instead of paging through [`list_chats`](#list-chats) when the question is how many chats there were, what share of answers rendered a shopping gallery or a map, or how many distinct prompts and engines a tag spans.

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `start_date` | string | Yes | Start date (YYYY-MM-DD) |
| `end_date` | string | Yes | End date (YYYY-MM-DD) |
| `dimensions` | string\[] | No | Group by: `prompt_id`, `model_id` (deprecated, prefer `model_channel_id`), `model_channel_id`, `tag_id`, `topic_id`, `date`, `week`, `month`, `country_code`, `chat_id`. Omit for a single total row. |
| `filters` | object\[] | No | Restrict which chats are counted. `{field, operator, values}` with operator `in` or `not_in`, AND'd together. Fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`. |
| `order_by` | object\[] | No | Sort by one or more fields (see [Sorting](#sorting)). Sorting by `date`, `week` or `month` requires that dimension. |
| `limit` | number | No | Max rows (default: 100, max: 1000) |
| `offset` | number | No | Rows to skip (default: 0) |

### Response fields

| Field | Description |
| - | - |
| `chat_count` | Chats in the group, and the denominator of every percentage below |
| `prompt_count` | Distinct prompts the group spans |
| `model_channel_count` | Distinct engine channels the group spans |
| `country_count` | Distinct countries the group spans, excluding chats with no country |
| `shopping_count` / `shopping_percentage` | Answers that rendered a shopping or product gallery |
| `product_comparison_count` / `product_comparison_percentage` | Answers that rendered a product comparison |
| `ad_count` / `ad_percentage` | Answers that carried an ad |
| `map_count` / `map_percentage` | Answers that rendered a map or local-business result |
| `web_search_count` / `web_search_percentage` | Answers built on web-search sources |

Percentages are 0-1 ratios of `chat_count`, so `0.75` means 75%. Rows grouped by `tag_id`, `topic_id` or `model_channel_id` also carry a matching `*_name` column.

<Info>
  Coverage counts collapse to 1 for whichever dimension you group by, so read `prompt_count`, `model_channel_count` and `country_count` against dimensions you didn't split on. Grouping by `prompt_id` makes `prompt_count` 1 in every row.
</Info>

<Tip>
  For a time or high-cardinality breakdown, raise `limit` to the row count you need rather than to the maximum. If `rowCount` comes back equal to `limit`, the results were truncated.
</Tip>

***

## list\_search\_queries

Lists the search sub-queries an AI engine fanned out to while answering prompts in a project over a date range. Each row is one sub-query issued for a given chat. Combine with `get_chat` to inspect the full response.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `start_date` | string | Yes | Start date (YYYY-MM-DD) |
| `end_date` | string | Yes | End date (YYYY-MM-DD) |
| `prompt_id` | string | No | Only queries from chats produced by this prompt |
| `chat_id` | string | No | Only queries from this chat |
| `model_id` | string | No | Only queries from this AI engine |
| `model_channel_id` | string | No | Only queries from this model channel |
| `topic_id` | string | No | Only queries from chats whose prompt belongs to this topic |
| `tag_id` | string | No | Only queries from chats whose prompt carries this tag |
| `limit` | number | No | Max results (default: 100, hard cap 1000) |
| `offset` | number | No | Results to skip (default: 0) |

**Columns:** `prompt_id`, `chat_id`, `model_id`, `model_channel_id`, `date`, `query_index`, `query_text`

***

## list\_shopping\_queries

Lists the product/shopping sub-queries an AI engine fanned out to while answering prompts. Each row is one shopping sub-query and the distinct products returned for it in a given chat.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `start_date` | string | Yes | Start date (YYYY-MM-DD) |
| `end_date` | string | Yes | End date (YYYY-MM-DD) |
| `prompt_id` | string | No | Only queries from chats produced by this prompt |
| `chat_id` | string | No | Only queries from this chat |
| `model_id` | string | No | Only queries from this AI engine |
| `model_channel_id` | string | No | Only queries from this model channel |
| `topic_id` | string | No | Only queries from chats whose prompt belongs to this topic |
| `tag_id` | string | No | Only queries from chats whose prompt carries this tag |
| `limit` | number | No | Max results (default: 100, max: 10000) |
| `offset` | number | No | Results to skip (default: 0) |

**Columns:** `prompt_id`, `chat_id`, `model_id`, `model_channel_id`, `date`, `query_text`, `products`

`products` is an array of product names extracted for that sub-query.

***

## list\_products

List a project's products with headline AI-visibility metrics over a date range.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `start_date` | string | Yes | Start date (YYYY-MM-DD) |
| `end_date` | string | Yes | End date (YYYY-MM-DD) |
| `search` | string | No | Filter by product or brand name |
| `source` | string | No | `CATALOG` (claimed, customer-uploaded) or `LLM` (AI-detected) |
| `chat_scope` | string | No | Visibility denominator: `shopping` (product-gallery chats, default) or `all` |
| `order_by` | string | No | `visibility` (default), `win_rate`, `avg_position`, `mention_count`, `name` |
| `direction` | string | No | `asc` or `desc` (default `desc`) |
| `tag_operator` | string | No | Match any (`or`, default) or all (`and`) of `tag_ids` |
| `brand_ids`, `category_ids`, `product_ids`, `merchant_ids`, `country_codes`, `model_channel_ids`, `topic_ids`, `tag_ids` | string\[] | No | Standard shopping filters. `brand_ids` are `global_brand_id` values; selecting a parent category also matches its descendants |
| `limit` | number | No | Max results (default: 100, max: 1000) |
| `offset` | number | No | Results to skip (default: 0) |

**Columns:** `id`, `name`, `brand`, `image_url`, `price_range`, `categories`, `mention_count`, `win_count`, `avg_position`, `visibility`, `share_of_voice`

***

## get\_product

Detailed metrics for one product over a date range — the drill-down companion to [`list_products`](#list-products).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `product_id` | string | Yes | The product id (resolve via `list_products`) |
| `start_date` | string | Yes | Start date (YYYY-MM-DD) |
| `end_date` | string | Yes | End date (YYYY-MM-DD) |
| `chat_scope` | string | No | `shopping` (default) or `all` |
| `country_codes`, `model_channel_ids`, `topic_ids`, `tag_ids` | string\[] | No | Metric filters |

**Returns:** `{ data, primary_currency }`. `data` is `null` if the product isn't in the project, otherwise: `id`, `name`, `brand`, `description`, `image_url`, `source`, `first_seen_at`, `price_range`, `visibility`, `win_rate`, `avg_position`, `mention_count`, a `*_delta` for each metric (vs the immediately preceding equal-length period), and `ai_price_map` / `ai_price_delta_map` (per-currency median price across the product's AI mentions).

***

## get\_shopping\_attributes

The LLM-extracted attribute grid — characteristics the AI associates with a product (or the whole catalog), compared against competitors.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `start_date` | string | Yes | Start date (YYYY-MM-DD) |
| `end_date` | string | Yes | End date (YYYY-MM-DD) |
| `scope` | string | No | `product` (default, needs `product_id`) or `overview` (whole catalog) |
| `product_id` | string | No | Required when `scope=product` |
| `tab` | string | No | `characteristics` (default), `facts`, or `dimensions` |
| `compare_by` | string | No | Grid columns: `brand` (default) or `product` (`scope=product` only) |
| `competitor_count` | number | No | Competitor columns (default: 6; `0` disables competitor lookup) |
| `category_ids`, `model_ids`, `model_channel_ids`, `country_codes`, `topic_ids`, `tag_ids` | string\[] | No | Filters |
| `search` | string | No | Substring match on dimension name |

**Returns:** a nested grid `{ tab, competitors[], groups[], total_groups }` (not columnar). Every group's per-competitor arrays align to the `competitors` order. Group shape depends on `tab` (`characteristics`, `facts`, or `dimensions`). Deltas are computed against an explicit comparison window (`previous_start_date` / `previous_end_date`) or the equal-length window immediately before.

***

## get\_shopping\_summary

Aggregate shopping metrics for a project over a date range, as a single columnar row. Deltas compare against the explicit `previous_start_date` / `previous_end_date` window when given, otherwise the auto-derived previous period.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `start_date` | string | Yes | Start date (YYYY-MM-DD) |
| `end_date` | string | Yes | End date (YYYY-MM-DD) |
| `previous_start_date`, `previous_end_date` | string | No | Explicit comparison window for deltas. Provide both, or omit both to auto-derive |
| `chat_scope` | string | No | Visibility denominator: `shopping` (default) or `all` |
| `brand_ids` | string\[] | No | Filter products to these `global_brand_id` values |
| `product_ids`, `category_ids`, `merchant_ids`, `country_codes`, `model_channel_ids`, `topic_ids`, `tag_ids` | string\[] | No | Standard shopping filters |
| `tag_operator` | string | No | Match any (`or`, default) or all (`and`) of `tag_ids` |
| `fields` | string\[] | No | Subset of columns to return |

**Columns:** `avg_visibility`, `avg_visibility_delta`, `avg_win_rate`, `avg_win_rate_delta`, `avg_position`, `avg_position_delta`

***

## get\_shopping\_trend

A product or brand shopping time series. Requires `bucket` and exactly one of `product_ids` or `brand_ids`.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `start_date` | string | Yes | Start date (YYYY-MM-DD) |
| `end_date` | string | Yes | End date (YYYY-MM-DD) |
| `bucket` | string | Yes | `day`, `week`, or `month` |
| `product_ids` | string\[] | Sometimes | Products to chart (exactly one of `product_ids` or `brand_ids`) |
| `brand_ids` | string\[] | Sometimes | `global_brand_id` values to chart (exactly one of `product_ids` or `brand_ids`) |
| `category_ids`, `merchant_ids`, `country_codes`, `model_channel_ids`, `topic_ids`, `tag_ids` | string\[] | No | Standard shopping filters |
| `tag_operator` | string | No | Match any (`or`, default) or all (`and`) of `tag_ids` |
| `fields` | string\[] | No | Subset of point fields to return |

**Returns:** a nested object `{ entity_type, series }` (not columnar). Each `series` entry is `{ entity_id, points }`, and each point carries `date`, `visibility`, `win_rate`, `avg_position`, `sov`, `has_data`.

***

## list\_shopping\_demand

Ranked shopping queries, search fan-out queries, or query terms over a date range — what shoppers are asking that surfaces your category.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `kind` | string | Yes | `shopping_query`, `fanout_query`, or `query_term` |
| `start_date` | string | Yes | Start date (YYYY-MM-DD) |
| `end_date` | string | Yes | End date (YYYY-MM-DD) |
| `previous_start_date`, `previous_end_date` | string | No | Explicit comparison window for `delta`. Provide both, or omit both to auto-derive |
| `mode` | string | No | `top` (default), `trending`, `losing`, or `new` |
| `category_ids`, `country_codes`, `model_channel_ids`, `topic_ids`, `tag_ids` | string\[] | No | Filters |
| `tag_operator` | string | No | Match any (`or`, default) or all (`and`) of `tag_ids` |
| `n` | number | No | n-gram width for `kind=query_term` (1–3, default 2) |
| `limit` | number | No | Max results (default: 20, max: 1000) |

**Columns:** `kind`, `text`, `distinct_chat_count`, `distinct_chat_count_previous`, `delta`

***

## list\_shopping\_performance

Ranked product or category shopping performance over a date range.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `entity_type` | string | Yes | `product` or `category` |
| `start_date` | string | Yes | Start date (YYYY-MM-DD) |
| `end_date` | string | Yes | End date (YYYY-MM-DD) |
| `previous_start_date`, `previous_end_date` | string | No | Explicit comparison window for deltas. Provide both, or omit both to auto-derive |
| `mode` | string | No | `top` (default), `trending`, or `losing` |
| `order_by` | string | No | `visibility` (default), `win_rate`, or `appearances` |
| `direction` | string | No | `asc` or `desc` (default `desc`) |
| `brand_ids` | string\[] | No | For products, filter to these `global_brand_id` values |
| `product_ids` | string\[] | No | Filter to these products |
| `category_id` | string | No | For categories, return only this category |
| `category_ids`, `merchant_ids`, `country_codes`, `model_channel_ids`, `topic_ids`, `tag_ids` | string\[] | No | Standard shopping filters |
| `tag_operator` | string | No | Match any (`or`, default) or all (`and`) of `tag_ids` |
| `limit` | number | No | Max results (default: 20, max: 1000) |
| `offset` | number | No | Results to skip (default: 0) |

**Columns:** `entity_type`, `entity_id`, `name`, `visibility`, `visibility_delta`, `win_rate`, `win_rate_delta`, `avg_position`, `avg_position_delta`, `appearances`, `appearances_delta`

***

## list\_merchants

Ranks the merchants whose product offers surfaced in AI answers over a date range, so you can see which sellers own the buy box for your category. A merchant is a seller such as Amazon or eBay, not a brand.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `start_date` | string | Yes | Start date (YYYY-MM-DD) |
| `end_date` | string | Yes | End date (YYYY-MM-DD) |
| `fields` | string\[] | No | Columns to return. Omit for all of them. |
| `category_ids` | string\[] | No | Narrow the population to these categories, for a per-category seller breakdown |
| `product_ids` | string\[] | No | Narrow the population to these products (from [`list_products`](#list-products)). Share of voice is then the share among that product's sellers. |
| `merchant_ids` | string\[] | No | Keep only these merchants' rows without shrinking the share-of-voice denominator, for comparing two known sellers |
| `order_by` | string | No | Metric to rank by: `mention_count` (default), `win_rate`, `avg_rating`, `avg_position` |
| `direction` | string | No | `asc` or `desc` (default: `desc`) |
| `limit` | number | No | Max results (default: 20, max: 200) |
| `offset` | number | No | Results to skip (default: 0) |

**Columns:** `merchant_id`, `name`, `domain`, `mention_count`, `share_of_voice`, `win_rate`, `avg_position`, `avg_rating`, and a `*_delta` for each metric against the previous window.

| Field | Description |
| - | - |
| `share_of_voice` | 0-1. This merchant's mentions over all merchants' mentions in the filtered population. |
| `win_rate` | 0-1 buy-box rate. Position-1 mentions over all mentions. |
| `avg_position` | Rank, so lower is better |
| `avg_rating` | Mean star rating out of 5, or `null` when the merchant is unrated |

Merchants with no mentions in the current window are left out entirely.

<Tip>
  Pass a `merchant_id` from here into [`get_product`](#get-product) as `merchant_ids` to see that seller's rating and price for a specific product.
</Tip>

***

## list\_categories

List the project's product categories. Categories are an org-wide tree (e.g. `Footwear > Shoes > Running Shoes`); each row carries its full `path` and `parent_id`, so the flat list rebuilds the tree. Use a row's `id` as a `category_id` when creating or updating products.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `fields` | string\[] | No | Subset of columns to return |

**Columns:** `id`, `name`, `path`, `parent_id`

***

## list\_global\_brands

Search Peec's global brand catalog — the shared registry of real-world brands (e.g. Nike, Apple) that products attach to. Use it to find the `global_brand_id` before [`create_products`](#create-products). This is **not** the same as [`list_brands`](#list-brands): that returns the brands tracked inside a project, while this searches every brand in Peec's catalog. The two have different ids.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `search` | string | No | Look up a brand by name or alias (the primary way to use this tool) |
| `ownership` | string | No | Instead of searching the catalog, list the project's shopping brands by `global_brand_id`, ranked by all-time shopping mentions: `own`, `competitor`, or `all` |
| `fields` | string\[] | No | Subset of columns to return |
| `limit` | number | No | Max results (default: 100, max: 1000) |
| `offset` | number | No | Results to skip (default: 0) |

**Columns:** `id`, `name`, `domain`, `description`, `mention_count`, `is_own`

***

## list\_bots

Lists every AI agent bot tracked in [Agent Analytics](/crawl-insights). Each entry has the bot's ID (the user agent string Peec matches), its provider, and its type. Use the returned IDs with [`get_agent_visits`](#get-agent-visits) to filter visit counts by specific bots.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `limit` | number | No | Max results (default: 1000, max: 10000) |
| `offset` | number | No | Results to skip (default: 0) |

**Returns:** `{ data: [{ id, provider, type }] }`.

| Field | Description |
| - | - |
| `id` | Bot identifier — the user agent name (e.g. `GPTBot`, `ClaudeBot`, `PerplexityBot`) |
| `provider` | Vendor behind the bot (e.g. `OpenAI`, `Anthropic`, `Google`) |
| `type` | Bot purpose. One of `training`, `search`, `userQuery`, `other` |

Bot types:

* `training` — crawlers that collect data to build or refine AI models (e.g. `GPTBot`, `ClaudeBot`)
* `search` — bots that browse the web to find up-to-date information for AI-powered search (e.g. `PerplexityBot`)
* `userQuery` — bots triggered by a real-time user query that fetch content on the user's behalf
* `other` — miscellaneous bots

<Note>
  Agent Analytics requires a connected data source (Cloudflare Workers or a CSV/CLF log upload). See [Crawl Insights](/crawl-insights) for setup.
</Note>

***

## get\_agent\_visits

Aggregate AI bot visit counts from your connected access logs over a date range. Without `group_by`, returns the total as a single `{ visits: N }` row. With `group_by`, returns one row per distinct value of the chosen dimension(s), sorted by `visits` descending.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `start_date` | string | Yes | Start date (YYYY-MM-DD) |
| `end_date` | string | Yes | End date (YYYY-MM-DD) |
| `group_by` | string\[] | No | Dimension(s) to group visit counts by. Omit for the total. Values: `bot_id`, `response_status`, `request_host`, `request_path`. |
| `bot_ids` | string\[] | No | Filter to specific bot IDs. Resolve via [`list_bots`](#list-bots). |
| `time_bucket` | string | No | Bucket results by time period. One of `hour`, `day`, `week`, `month`. Each row gets a `time_bucket` timestamp marking the start of the bucket. |
| `limit` | number | No | Max grouped rows (default: 100, max: 10000) |
| `offset` | number | No | Grouped rows to skip (default: 0) |

### Group-by dimensions

| Dimension | Description |
| - | - |
| `bot_id` | Break down by bot. Combine with [`list_bots`](#list-bots) to resolve IDs to provider names. |
| `response_status` | Break down by HTTP response status (`200`, `404`, etc.) |
| `request_host` | Break down by hostname |
| `request_path` | Break down by URL path |

Multiple values produce a cross-dimensional breakdown — for example, `["bot_id", "response_status"]` gives per-bot, per-status counts. Combine with `time_bucket` to get e.g. per-bot, per-day counts.

### Response fields

`{ data: [...], totalCount }`.

| Field | Description |
| - | - |
| `visits` | Visit count for the row |
| `bot_id` | Present when `bot_id` is in `group_by` |
| `response_status` | Present when `response_status` is in `group_by` |
| `request_host` | Present when `request_host` is in `group_by` |
| `request_path` | Present when `request_path` is in `group_by` |
| `time_bucket` | Present when `time_bucket` is set. ISO-style timestamp marking the start of the bucket. |
| `totalCount` | Total grouped rows ignoring `limit`/`offset`. Equals `1` when `group_by` is omitted. |

<Tip>
  Pair `get_agent_visits` with the report tools to connect bot activity to AI visibility. For example, `request_path` grouping surfaces which of your pages bots hit most; [`get_url_report`](#get-url-report) shows how those same pages perform as AI sources.
</Tip>

***

## get\_ai\_referrals

People who arrived on your own website from an AI assistant, measured through the project's connected Google Analytics property. This is traffic that reached your site, which is a different question from whether AI answers cite you ([`get_url_report`](#get-url-report)) or whether AI crawlers fetch your pages ([`get_agent_visits`](#get-agent-visits)).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `start_date` | string | Yes | Start date (YYYY-MM-DD). Ranges are capped at 366 days. |
| `end_date` | string | Yes | End date (YYYY-MM-DD) |
| `group_by` | string\[] | No | Up to 3 dimensions. Omit for period totals. Pass exactly one to list that dimension's values. |
| `metrics` | string\[] | No | `events`, `session_starts`, `conversions`, `revenue`. Omit for all of them. |
| `time_bucket` | string | No | `day`, `week` or `month`. Adds a `time_bucket` column holding the first day of each bucket. There's no hourly bucket, because the data is daily. |
| `assistants` | string\[] | No | Filter by assistant display name. Names must match exactly and an unrecognized one is rejected rather than ignored, so resolve them with [`list_referral_sources`](#list-referral-sources). |
| `sources` | string\[] | No | Filter by raw referrer host, e.g. `chatgpt.com` |
| `countries` | string\[] | No | ISO 3166-1 alpha-2 country codes |
| `devices` | string\[] | No | Device categories such as `mobile`. Property-specific and case-sensitive: an unmatched value returns zeros rather than an error. |
| `event_names` | string\[] | No | GA4 event names. Property-specific, so discover them with `group_by: ["event_name"]` first. |
| `mediums` | string\[] | No | GA4 session mediums, e.g. `ai-assistant`, to isolate traffic identified by medium rather than by a known referrer host |
| `order_by` | string | No | Must be one of the requested metrics, or `time_bucket` |
| `limit` | number | No | Max grouped rows |
| `offset` | number | No | Grouped rows to skip |

### Group-by dimensions

| Dimension | Description |
| - | - |
| `assistant` | ChatGPT, Perplexity, Claude, Gemini, Copilot, Grok and around 57 more. Rolls up every host an assistant uses, so prefer it over `source`. |
| `platform` | The company behind the assistants: OpenAI, Google, Microsoft, Anthropic and so on |
| `source` | The raw referrer host. Rows grouped by `source` also carry `assistant` and `platform`, so naming a host never needs a second call. An unrecognized referrer appears under its own hostname. |
| `medium` | GA4 session medium. Only `ai-assistant` and the mediums AI referrers arrive on, since non-AI traffic is out of scope here. |
| `country` | ISO country code |
| `device` | `desktop`, `mobile` or `tablet` |
| `event_name` | The GA4 event, such as `page_view` or `purchase` |
| `landing_page` | The session's entry page, repeated on every event in that session |
| `page_path` | The page the event fired on, with UUIDs collapsed to `*`. Doesn't join to `landing_page`. |
| `host` | Which of your own hostnames |

### Response fields

`{ columns, rows, rowCount, total_count, currency }`.

| Field | Description |
| - | - |
| `events` | GA4 event count |
| `session_starts` | GA4 `session_start` events. Not GA4's "sessions" metric. |
| `conversions` | GA4 key events. One visit can contribute several, and which events count is your property's own configuration. |
| `revenue` | Purchase revenue in the property's reporting currency, which comes back as `currency` on the result |
| `total_count` | The number of grouped rows the filters match, not a sum of any metric |

Unknown dimension values come back as `(not set)`.

<Info>
  There's no `list_event_names` or `list_countries` tool. To discover a dimension's values, call this with `group_by` set to that one dimension. When you build a filter, don't also filter on the dimension you're listing, or every option you haven't already picked disappears.
</Info>

<Info>
  Referral figures are a lower bound. Only referrer-visible traffic reaches GA4, so assistant native apps land as Direct and Gemini often counts as Organic Search.
</Info>

***

## list\_referral\_sources

Every AI assistant Peec can attribute referral traffic to, whether or not your project has seen traffic from it. Use it to resolve the exact display name for the `assistants` filter on [`get_ai_referrals`](#get-ai-referrals), and to recognize a raw host in that tool's results.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `fields` | string\[] | No | Columns to return. Omit for all of them. |
| `limit` | number | No | Max rows (default and max: 1000) |
| `offset` | number | No | Rows to skip (default: 0) |

**Columns:** `source`, `assistant`, `platform`

One row per referrer host, so an assistant reachable on several hosts appears once per host. The list is maintained by hand and reviewed quarterly, so a very new assistant may be missing.

<Info>
  This tool takes no `project_id` and no date range. For the assistants that actually sent your project traffic, call [`get_ai_referrals`](#get-ai-referrals) with `group_by: ["assistant"]` instead.
</Info>

***

## list\_domain\_classifications

Lists the custom domain classifications defined for a project. These complement the built-in classifications (`Corporate`, `Competitor`, `Editorial`, `Institutional`, `Other`, `Reference`, `UGC`, `You`, `Related`) and can be assigned to specific domains via [`assign_domain_classification`](#assign-domain-classification).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `limit` | number | No | Max results (default: 100) |
| `offset` | number | No | Results to skip (default: 0) |

**Columns:** `name`, `color`

***

## list\_url\_classifications

Lists the custom URL classifications defined for a project. These complement the built-in classifications (`Homepage`, `Category Page`, `Product Page`, `Listicle`, `Comparison`, `Profile`, `Alternative`, `Discussion`, `How-To Guide`, `Article`, `Other`) and can be assigned to specific URLs via [`assign_url_classification`](#assign-url-classification).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `limit` | number | No | Max results (default: 100) |
| `offset` | number | No | Results to skip (default: 0) |

**Columns:** `name`, `color`

***

## get\_brand\_report

Returns brand visibility, sentiment, position, and share of voice across AI search engines.

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `start_date` | string | Yes | Start date (YYYY-MM-DD) |
| `end_date` | string | Yes | End date (YYYY-MM-DD) |
| `limit` | number | No | Max results (default: 100) |
| `offset` | number | No | Results to skip (default: 0) |
| `dimensions` | string\[] | No | Break down by: `prompt_id`, `model_id` (deprecated, prefer `model_channel_id`), `model_channel_id`, `tag_id`, `topic_id`, `date`, `country_code`, `chat_id` |
| `filters` | object\[] | No | Filter results (see [Filtering](#filtering)) |
| `order_by` | object\[] | No | Sort by one or more fields (see [Sorting](#sorting)). Sortable: `visibility`, `visibility_count`, `mention_count`, `sentiment`, `position`, `share_of_voice`. |

### Response fields

| Field | Type | Description |
| - | - | - |
| `brand_id` | string | The brand ID |
| `brand_name` | string | The brand name |
| `visibility` | number | 0 to 1. Fraction of AI responses that mention the brand |
| `mention_count` | number | Total times the brand was mentioned |
| `share_of_voice` | number | 0 to 1. Brand's share of total mentions across all brands |
| `sentiment` | number | 0 to 100. How positively AI platforms describe the brand. Most brands score 65 to 85 |
| `position` | number | Average rank when mentioned. Lower is better (1 = mentioned first) |

The response also includes raw aggregation fields (`visibility_count`, `visibility_total`, `sentiment_sum`, `sentiment_count`, `position_sum`, `position_count`) for custom calculations across segments.

***

## get\_domain\_report

Returns source domain retrieval and citation metrics across AI search engines.

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `start_date` | string | Yes | Start date (YYYY-MM-DD) |
| `end_date` | string | Yes | End date (YYYY-MM-DD) |
| `limit` | number | No | Max results (default: 100) |
| `offset` | number | No | Results to skip (default: 0) |
| `dimensions` | string\[] | No | Break down by: `prompt_id`, `model_id` (deprecated, prefer `model_channel_id`), `model_channel_id`, `tag_id`, `topic_id`, `date`, `country_code`, `chat_id` |
| `filters` | object\[] | No | Filter results (see [Filtering](#filtering)) |
| `order_by` | object\[] | No | Sort by one or more fields (see [Sorting](#sorting)). Sortable: `citation_rate`, `retrieval_count`, `citation_count`. (`retrieved_percentage` and `retrieval_rate` are computed from a separate aggregate and aren't sortable.) |

### Response fields

| Field | Type | Description |
| - | - | - |
| `domain` | string | The source domain (e.g. `example.com`) |
| `classification` | string | Domain type: `You`, `Corporate`, `Editorial`, `Institutional`, `UGC`, `Reference`, `Competitor`, `Related`, `Other`, the name of a custom classification, or `null` |
| `retrieved_percentage` | number | 0 to 1. Fraction of chats that retrieved this domain |
| `retrieval_rate` | number | Average URLs retrieved per chat. Can exceed 1.0 (this is an average, not a percentage) |
| `citation_rate` | number | Average citations per distinct chat that retrieved this domain: `citation_count / retrieved_chat_count`. Can exceed 1.0. This is **not** `citation_count / retrieval_count` — dividing by `retrieval_count` gives the per-retrieval average, which is the deprecated `citation_avg` |
| `retrieval_count` | number | Total distinct URL retrievals from this domain across all chats (raw numerator of `retrieval_rate`). A single chat can retrieve several URLs from the same domain, so this is `>= retrieved_chat_count` |
| `citation_count` | number | Total citations from this domain (raw count) |
| `retrieved_chat_count` | number | Number of distinct chats in which this domain was retrieved (denominator of `citation_rate`) |
| `mentioned_brand_ids` | string\[] | Brand IDs mentioned alongside URLs from this domain (may be empty) |

***

## get\_url\_report

Returns URL-level retrieval and citation metrics across AI search engines.

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `start_date` | string | Yes | Start date (YYYY-MM-DD) |
| `end_date` | string | Yes | End date (YYYY-MM-DD) |
| `limit` | number | No | Max results (default: 100) |
| `offset` | number | No | Results to skip (default: 0) |
| `dimensions` | string\[] | No | Break down by: `prompt_id`, `model_id` (deprecated, prefer `model_channel_id`), `model_channel_id`, `tag_id`, `topic_id`, `date`, `country_code`, `chat_id` |
| `filters` | object\[] | No | Filter results (see [Filtering](#filtering)) |
| `order_by` | object\[] | No | Sort by one or more fields (see [Sorting](#sorting)). Sortable: `retrieval_count`, `retrievals` (deprecated alias of `retrieval_count`), `citation_count`, `citation_rate`. |

### Response fields

| Field | Type | Description |
| - | - | - |
| `url` | string | The full source URL |
| `classification` | string | Page type: `Homepage`, `Category Page`, `Product Page`, `Listicle`, `Comparison`, `Profile`, `Alternative`, `Discussion`, `How-To Guide`, `Article`, `Other`, the name of a custom classification, or `null` |
| `title` | string | Page title (may be `null`) |
| `channel_title` | string | Channel or author name for YouTube videos, Reddit threads, etc. (may be `null`) |
| `citation_count` | number | Total citations across all chats |
| `retrieval_count` | number | Total distinct chats that retrieved this URL |
| `citation_rate` | number | Average citations per retrieval. Can exceed 1.0 |
| `mentioned_brand_ids` | string\[] | Brand IDs mentioned alongside this URL (may be empty) |

***

## get\_url\_content

Returns the scraped markdown content of a source URL Peec has indexed. Use this after `get_url_report` to inspect the actual content an AI engine read. Useful for content gap analysis and comparing why a competitor URL wins citations.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `url` | string | Yes | Full URL of a source. Copy it verbatim from `get_url_report`. Trailing slashes and scheme variations change the resolved source ID. |
| `max_length` | number | No | Cap on returned content length in characters. Increase and re-request if `truncated` is `true`. |

### Response fields

| Field | Type | Description |
| - | - | - |
| `url` | string | The requested URL |
| `title` | string | Page title (may be `null`) |
| `domain` | string | The source domain |
| `channel_title` | string | Channel or author name for YouTube videos, Reddit threads, etc. (may be `null`) |
| `classification` | string | Domain-level classification (same values as `get_domain_report`) |
| `url_classification` | string | Page-level classification (same values as `get_url_report`) |
| `content` | string | Markdown extracted via Readability + Turndown. `null` if Peec has tracked the URL but scraping has not completed yet (can take up to 24h) |
| `content_length` | number | Original character length before truncation. `0` when content is `null` |
| `truncated` | boolean | `true` if content was truncated to `max_length` |
| `content_updated_at` | string | ISO timestamp of last scrape, or `null` if not yet scraped |

Returns a 404 if the URL has never been retrieved by any Peec project. Peec only scrapes URLs that appear as AI sources.

***

## get\_brand\_perception\_brand\_attributes

How AI models describe your own brand: attribute clusters such as "Luxury" or "Racing Heritage", each with a prominence score. This is the [Brand Perception](/brand-perception) market view, read as data.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `fields` | string\[] | No | Columns to return. Omit for all of them. |
| `model_channel_ids` | string\[] | No | Only answers from these engine channels (from [`list_model_channels`](#list-model-channels)). Omit to aggregate across every tracked channel. |
| `limit` | number | No | Max results (default: 100, max: 1000) |
| `offset` | number | No | Results to skip (default: 0) |

**Columns:** `name`, `score`, `members`

| Field | Description |
| - | - |
| `score` | 0-100. The attribute's average prominence per AI answer, so a higher score means it's mentioned earlier and more often. |
| `members` | The raw extracted attributes folded into the cluster |

This one is a snapshot of the latest brand-perception run, where the ranking and competitive-breakdown tools below aggregate across many runs. An empty result means the first run hasn't completed yet.

<Info>
  Scores here are not ratios. Display them as returned and never multiply by 100. Brand Perception carries no date range, so none of these tools accepts one.
</Info>

***

## get\_brand\_perception\_attribute\_rankings

Where your own brand places against competitors on each brand-perception attribute, and which attributes it has never surfaced on at all.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `fields` | string\[] | No | Columns to return. Omit for all of them. |
| `model_channel_ids` | string\[] | No | Only answers from these engine channels (from [`list_model_channels`](#list-model-channels)) |
| `industry` | string | No | Read the runs dispatched for this industry. Omit for the project's default, which is the industry with the most recent completed run. |
| `search` | string | No | Case-insensitive substring filter on the attribute name |
| `limit` | number | No | Max results (default: 100, max: 1000) |
| `offset` | number | No | Results to skip (default: 0) |

**Columns:** `name`, `ranking`, `competitors`

| Field | Description |
| - | - |
| `ranking` | Your brand's position among every brand scored for the attribute, ordered by average prominence. Lower is better, and `#1` means no brand is more prominent. Answers your brand never surfaced in count against it. |
| `competitors` | The competing brand names AI associates with the attribute, most prominent first |

Rows come back best-ranked first, with unranked last. A `ranking` of `null` means your brand has never once been described that way, which is a different problem from ranking fourth.

The response also reports the `industry` and `target_market` it read, and lists your other industries under `industries` when the project has more than one. Say which industry a number describes whenever that field is present. The target market is always the industry's most recently completed one and can't be picked.

<Tip>
  Pass a returned `name` to [`get_brand_perception_attribute_sources`](#get-brand-perception-attribute-sources) to see which pages are feeding that attribute.
</Tip>

***

## get\_brand\_perception\_competitive\_breakdown

The full attribute by brand matrix: for every attribute, the average prominence of your brand and each competitor across AI answers.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `fields` | string\[] | No | Columns to return. Omit for all of them. |
| `model_channel_ids` | string\[] | No | Only answers from these engine channels (from [`list_model_channels`](#list-model-channels)) |
| `industry` | string | No | Read the runs dispatched for this industry. Omit for the project's default. |
| `limit` | number | No | Max attributes (default: 100, max: 1000) |
| `offset` | number | No | Attributes to skip (default: 0) |

**Columns:** `attribute`, `brand`, `score`, `is_own`

`score` is 0-100, where higher means the brand tends to be mentioned earlier when AI talks about that attribute. `is_own` marks your brand. One row per attribute and brand cell, with attributes sorted by your own score, strongest first, and brands sorted by score within each attribute.

<Info>
  `limit` and `offset` paginate **attributes**, not rows. Each attribute contributes one row per brand, and `totalCount` is the attribute count. Set `limit` generously and check `totalCount` before assuming you have the whole matrix.
</Info>

***

## get\_brand\_perception\_attribute\_sources

The pages feeding one attribute: the URLs AI answers cited while describing your brand that way. These are the pages to go after when you want to change how AI describes you on it.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `attribute` | string | Yes | The attribute name, exactly as the attribute tools returned it |
| `fields` | string\[] | No | Columns to return. Omit for all of them. |
| `model_channel_ids` | string\[] | No | Only answers from these engine channels (from [`list_model_channels`](#list-model-channels)) |
| `order_by` | object\[] | No | Sort by `occurrences`, `retrievals` or `citation_rate`. Defaults to `occurrences` descending. |
| `limit` | number | No | Max results (default: 100, max: 1000) |
| `offset` | number | No | Results to skip (default: 0) |

**Columns:** `url`, `title`, `domain`, `url_classification`, `domain_classification`, `occurrences`, `retrievals`, `citation_rate`

| Field | Description |
| - | - |
| `occurrences` | AI answers about this attribute that cited the source. This is the influence number. |
| `retrievals` | Distinct chats the source was retrieved in |
| `citation_rate` | Mean citations per retrieved chat |

<Info>
  Pass the attribute name verbatim. An unknown name returns an empty result rather than an error, so a paraphrase looks like "no sources". Unlike the rankings and breakdown tools, this one isn't scoped to an industry and takes no `industry` argument.

  <br />

  <br />

  `citation_rate` is an average, not a percentage. It can exceed 1. Display it as returned.
</Info>

***

## get\_brand\_perception\_objections

The recurring arguments AI makes against your brand when a buyer is deciding. An attribute measures how strongly AI links you to a quality. An objection is the engine arguing against buying you at all.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `fields` | string\[] | No | Columns to return. Omit for all of them. |
| `model_channel_ids` | string\[] | No | Only answers from these engine channels (from [`list_model_channels`](#list-model-channels)) |
| `limit` | number | No | Max results (default: 100, max: 1000) |
| `offset` | number | No | Results to skip (default: 0) |

**Columns:** `name`, `score`, `members`

`score` is average prominence per AI answer from 0 to 100, displayed as returned. `members` holds the raw phrasings folded into each objection: a "Pricing" objection made of *expensive for what you get* is a different problem from one made of *pricing is hard to find*.

There's no competitor dimension and no ranking here, because the objection is about your brand alone. Data aggregates across every objection run and takes no industry argument.

***

## get\_brand\_perception\_objection\_sources

The pages AI models retrieved when asked about one objection.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `objection` | string | Yes | The objection name, exactly as [`get_brand_perception_objections`](#get-brand-perception-objections) returned it |
| `fields` | string\[] | No | Columns to return. Omit for all of them. |
| `model_channel_ids` | string\[] | No | Only answers from these engine channels (from [`list_model_channels`](#list-model-channels)) |
| `order_by` | object\[] | No | Sort by `occurrences`, `retrievals` or `citation_rate` |
| `limit` | number | No | Max results (default: 100, max: 1000) |
| `offset` | number | No | Results to skip (default: 0) |

Returns the same columns as [`get_brand_perception_attribute_sources`](#get-brand-perception-attribute-sources), with the same meanings. An unknown objection name returns an empty result rather than an error, and `citation_rate` is an average rather than a percentage.

***

## list\_brand\_perception\_attribute\_clusters

The editable attribute taxonomy behind Brand Perception: every cluster with its ID, its label, and the raw extracted attributes grouped under it. Read this when an attribute looks mislabeled, duplicated or split, and to resolve the `cluster_id` values that [`edit_brand_perception_attribute_clusters`](#edit-brand-perception-attribute-clusters) needs.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `fields` | string\[] | No | Columns to return. Omit for all of them. |
| `limit` | number | No | Max clusters (default: 100, max: 1000) |
| `offset` | number | No | Clusters to skip (default: 0) |

**Returns:** `{ columns, rows, rowCount, totalCount, unassigned }`.

**Columns:** `cluster_id`, `name`, `is_custom`, `members`

| Field | Description |
| - | - |
| `is_custom` | Marks a cluster someone added by hand |
| `unassigned` | Extracted attributes that belong to no cluster. Not paginated. |

This tool carries no scores, so use [`get_brand_perception_brand_attributes`](#get-brand-perception-brand-attributes) when the question is about scores. It does list clusters that have no score yet, which that tool won't show.

***

## list\_facts

The facts your project uses to check claims found in AI answers. A manual fact was added by a person; a website fact was extracted from your own site.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `origin` | string | No | Filter by how the fact was added: `manual` or `website` |
| `is_active` | boolean | No | Filter by whether the fact is used in future fact-checking |
| `fields` | string\[] | No | Columns to return. Omit for all of them. |
| `limit` | number | No | Max results (default: 100, max: 1000) |
| `offset` | number | No | Results to skip (default: 0) |

**Columns:** `id`, `text`, `origin`, `is_active`, `edited_at`, `created_at`

Results are newest first. An inactive fact stays visible here but is left out of future fact-checking. Deleted facts are never returned.

<Tip>
  Call this first to resolve fact IDs before [`update_facts`](#update-facts) or [`delete_facts`](#delete-facts).
</Tip>

***

## get\_actions

Returns Peec's opportunity-scored action recommendations for a project and date range. Use this whenever the user asks what to do next, how to improve visibility, or wants ranked next steps instead of raw data.

The tool is two-step: always call `scope=overview` first to see which slices have the biggest opportunity, then drill into `owned`, `editorial`, `reference`, or `ugc` for the actual textual recommendations.

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `start_date` | string | Yes | Start date (YYYY-MM-DD) |
| `end_date` | string | Yes | End date (YYYY-MM-DD) |
| `scope` | string | Yes | One of `overview`, `owned`, `editorial`, `reference`, `ugc` |
| `tag_ids` | string\[] | No | Only include actions matching these tags |
| `topic_ids` | string\[] | No | Only include actions for these topics |
| `model_ids` | string\[] | No | Only include actions for these AI models |
| `model_channel_ids` | string\[] | No | Only include actions for these model channels |
| `country_codes` | string\[] | No | ISO 3166-1 alpha-2 codes (e.g. `US`, `DE`) |
| `url_classification` | string | Sometimes | Required for `scope=editorial`, optional for `scope=owned`. Page types like `LISTICLE`, `ARTICLE`, `COMPARISON`. Pass values surfaced by an `overview` row. |
| `domain` | string | Sometimes | Required for `scope=reference` and `scope=ugc` (e.g. `wikipedia.org`, `reddit.com`). Pass values surfaced by an `overview` row. |

### Response (`scope=overview`)

| Field | Type | Description |
| - | - | - |
| `action_group_type` | string | `OWNED`, `EDITORIAL`, `REFERENCE`, or `UGC` |
| `url_classification` | string | Page type for OWNED / EDITORIAL rows (`null` for REFERENCE / UGC) |
| `domain` | string | Domain for REFERENCE / UGC rows (`null` for OWNED / EDITORIAL) |
| `opportunity_score` | number | Continuous score. Sort and rank by this. |
| `relative_opportunity_score` | number | Strength tier: `1` = Low, `2` = Medium, `3` = High. Use this for prose labels. |
| `gap_percentage`, `coverage_percentage`, `used_ratio`, `used_total` | number | Supporting stats |

Each overview row surfaces exactly one of `url_classification` or `domain`. Pass that value into the matching scope in the follow-up call.

### Response (`scope=owned` | `editorial` | `reference` | `ugc`)

| Field | Type | Description |
| - | - | - |
| `text` | string | The recommendation, may include markdown links to targets or examples |
| `group_type` | string | `OWNED`, `EDITORIAL`, `REFERENCE`, or `UGC` |
| `url_classification` | string | Page type (may be `null`) |
| `domain` | string | Domain (may be `null`) |
| `opportunity_score` | number | Continuous score. Sort and rank by this. |
| `relative_opportunity_score` | number | Strength tier: `1` = Low, `2` = Medium, `3` = High. |

<Tip>
  For example: `scope=overview` returns a row `{action_group_type: "UGC", domain: "youtube.com", opportunity_score: 0.30, ...}`. Follow up with `scope=ugc, domain="youtube.com"` to get ranked recommendations like "Contact [AutoPedia](https://...). Ask them for a collaboration."
</Tip>

***

## list\_actions

The actions Peec generated for your project, the same set the Actions page shows. Each action names a page or a site and a concrete change to make to it, with the impact expected if you do it.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `types` | string\[] | No | `TEMPLATE_ACTION`, `CONTENT_BRIEF`, `CATEGORY_SITUATION_BRIEF`, `CONTRADICTIONS_EXTERNAL_SOURCES`, `CONTRADICTIONS_OWNED_SOURCES`, `SEO_ISSUE`, `ROBOTS_TXT`, `PDP_OPTIMISATION`, `MANUAL_ACTION`, and `CONTENT_OPTIMISATION` (only on projects with Content optimization enabled). Omit for every published type. |
| `statuses` | string\[] | No | `PENDING` is untouched, `ACCEPTED` is in progress, `COMPLETED` is done, `REJECTED` was declined. Omit for every status. |
| `categories` | string\[] | No | The off-site playbook a template action follows, or the audit check an `SEO_ISSUE` came from. Content briefs and `ROBOTS_TXT` actions carry no category. |
| `domains` | string\[] | No | The site an `SEO_ISSUE` was raised against. Every other type carries no domain. |
| `topic_ids` | string\[] | No | Only actions on these topics (from [`list_topics`](#list-topics)) |
| `model_channel_ids` | string\[] | No | Only actions affecting these engine channels |
| `country_codes` | string\[] | No | ISO 3166-1 alpha-2 markets. An action carrying no market isn't scoped to one, so every selection matches it. |
| `targets` | string\[] | No | `owned` lands on a page you control, `earned` on a third-party page. A user-generated content (UGC) action is `earned` even when you write the post yourself. |
| `groups` | string\[] | No | The kind of surface the action lands on |
| `archetypes` | string\[] | No | The kind of page a content brief says to create. Template actions carry no archetype, so this narrows the answer to content briefs. |
| `platforms` | string\[] | No | Registrable domain of a third-party site (from [`list_action_platforms`](#list-action-platforms)). Own-site actions match nothing here. |
| `fields` | string\[] | No | Columns to return. Naming any column replaces the default set entirely, so include the ones you still want. |
| `order_by` | string | No | `impact` (default) is the order the Actions page shows, strongest expected gain first. `created_at` reads newest first, which is how to find what Peec generated since you last looked. |
| `direction` | string | No | `asc` or `desc` (default: `desc`) |
| `limit` | number | No | Max results (default: 100, max: 1000) |
| `offset` | number | No | Results to skip (default: 0) |

**Default columns:** `id`, `type`, `status`, `title`, `group`, `category`, `target`, `archetype`, `platform`, `domain`, `topic_id`, `source`, `impact`, `step_count`, `created_at`, `created_by`

**Also available via `fields`:** `country_codes`, `model_channel_ids`, `completed_step_count`, `status_updated_at`, `priority`, `assignee_user_id`, `due_on`, `tag_ids`

The list holds both the actions Peec generated and the ones you wrote yourself. `created_by` says which: `peec` or `customer`. Only a `customer` action can be deleted or have its `kind` changed. `priority`, `assignee_user_id`, `due_on`, and `tag_ids` are how you use the Actions page as a task tracker.

The published types differ in what they ask of you. `CONTRADICTIONS_EXTERNAL_SOURCES` requests a correction to one third-party source page, while `CONTRADICTIONS_OWNED_SOURCES` corrects one source page on a domain you own. `TEMPLATE_ACTION` is a per-platform playbook filled in for one page, such as pitching an editor or growing reviews. `CONTENT_BRIEF` is net-new content to write, with an outline. `CATEGORY_SITUATION_BRIEF` is also net-new content, with ready-to-use briefs carried in its steps rather than an outline. `SEO_ISSUE` is a technical fix to a site you control, and applies to the whole site rather than one page. `ROBOTS_TXT` says a site's `robots.txt` blocks AI crawlers. `PDP_OPTIMISATION` improves one product page. `MANUAL_ACTION` is work you described yourself that matches none of the other shapes. `CONTENT_OPTIMISATION` improves an existing page you own. [`get_optimize_content`](#get-optimize-content) returns its article, suggestions, and score.

`CONTENT_OPTIMISATION` actions follow the same rules as the Actions page. They appear only when **Content optimization** is enabled for the project.

`impact` is how much the action is expected to gain, banded against every action in the project, so it reads the same whatever filters you apply. On an `SEO_ISSUE` it bands the issue's severity instead. It's the only measure of expected gain this tool returns.

<Info>
  Filters combine with AND, with one exception: `targets`, `groups`, `archetypes` and `platforms` combine with OR across the four, so passing an owned target alongside a platform widens the answer instead of narrowing it.
</Info>

<Info>
  [`get_actions`](#get-actions) is a different, older opportunity-rollup tool. Fall back to it only when this one reports the feature isn't enabled for the project.
</Info>

***

## get\_action

One action in full: what to do, the content brief when there is one, and the competitor demand behind it. Everything [`list_actions`](#list-actions) returns is here too.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `action_id` | string | Yes | The action ID, copied verbatim from `list_actions` |
| `fields` | string\[] | No | Extra fields to include (default: none) |

Always returned: `title`, `description` (the case for the action, with its sources), the fields you own on the action (`kind`, `notes`, `page_url`, `priority`, `assignee_user_id`, `due_on`, `tag_ids`, `repeat`, `time_range`, `language_codes`), `content_brief_outline` (content briefs only, holding the headline options, meta title and description, your angle, the facts you may claim, the points to cover, and the whole brief as one markdown document), and `opportunity` (the competitor demand a brief answers, also briefs only). A site-audit action, `SEO_ISSUE` or `ROBOTS_TXT`, carries neither, and its `description` and steps are the whole fix. `kind` is what you wrote the action as, and is `null` on an action Peec generated.

| Extra field | What it adds |
| - | - |
| `steps` | On a template action, the work itself: each step holds one or more options, and an option is a concrete edit with the text to use. On a content brief they're instead the material the brief was written from, labeled by `gap_type`: the fan-out prompts, what communities say, and the sources winning the topic today. |
| `outline_points` | The content brief section by section: what each one argues, the questions it answers, and the evidence behind it |
| `impacted_prompts` | The prompts this action affects. For source corrections, `own_coverage_score` is your owned domains’ share of all citations for the prompt in the action’s analysis window. Other types use their documented page-coverage score. |
| `ngrams` | Terms competitors use on the topic that your own pages don't. Template actions only. |

<Tip>
  `steps` and `outline_points` are each most of the response for their kind of action, so ask for them when you're about to do the work rather than while browsing.
</Tip>

An ID this project has no published action for is an error, whether it belongs to another project, to an action type this tool doesn't publish for the project, or to nothing at all.

For a `CONTENT_OPTIMISATION` action, [`get_optimize_content`](#get-optimize-content) returns the article, its suggestions, and the score.

***

## list\_action\_platforms

The third-party sites your project has actions on, alphabetically. These are the values [`list_actions`](#list-actions) accepts in its `platforms` filter.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |

**Columns:** `platform`

A platform is whichever domain an AI engine cited for your brand, so unlike the other filter dimensions it's per project and open-ended. Own-site actions carry no platform and never appear here.

***

## get\_optimize\_content

Reads the article behind a `CONTENT_OPTIMISATION` action, as you see it on the Optimize content screen: the current text, the suggestions beside it, and the optimization score. Only available when **Content optimization** is enabled for the project.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `action_id` | string | Yes | The ID of a `CONTENT_OPTIMISATION` action, copied verbatim from [`list_actions`](#list-actions) |

**Returns:** `{data}` with these fields:

| Field | Description |
| - | - |
| `action_id` | The action the article belongs to |
| `page_url` | The page being optimized |
| `score` | The optimization score out of 100, reflecting the suggestions accepted so far |
| `article` | The whole article as plain text, with suggestions resolved the way the screen shows them: an accepted rewrite reads as its new wording, a pending or dismissed one as the original |
| `suggestions` | One entry per suggestion, each with `id`, `category`, `text`, `state` (`pending`, `accepted`, or `rejected`), and `kind` |

A suggestion's `kind` decides how you act on it. A `rewrite` carries wording you can accept or dismiss with [`resolve_optimize_content_suggestions`](#resolve-optimize-content-suggestions). An `edit` only names what's missing, so carrying it out means writing the text with [`edit_optimize_content`](#edit-optimize-content).

An action that isn't a content optimization, is deleted, or belongs to another project is an error.

***

## get\_project\_profile

Read the project's brand profile: the description, industry, brand-identity adjectives, target markets, audience distribution, and product or service list that Peec uses to generate prompt suggestions. Call this before `set_project_profile` so the assistant can show you the current values before changing anything.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |

**Returns:** `{ profile }`. `profile` is `null` if the project hasn't been profiled yet, otherwise an object with the fields described under [`set_project_profile`](#set-project-profile).

***

## search\_docs

Search the Peec product documentation at [docs.peec.ai](https://docs.peec.ai) and return the most relevant pages. The assistant uses this for any question about how Peec works — what a metric means, how a feature behaves, setup steps, plan and credit rules — then reads the best result with [`read_doc`](#read-doc). Needs no `project_id` or project access.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `query` | string | Yes | Search terms, e.g. `share of voice` or `set up prompts` |
| `limit` | number | No | Max pages to return (default: 5, max: 20) |

**Columns:** `title`, `path`, `url`, `snippet`

Pass a result's `path` to [`read_doc`](#read-doc).

***

## read\_doc

Read the full markdown content of a single documentation page. Pass the `path` returned by [`search_docs`](#search-docs) (e.g. `metrics/brand-metrics/visibility`). Needs no `project_id` or project access.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `path` | string | Yes | Page path from a `search_docs` result |

**Returns:** `{ title, path, url, content }`. Returns a 404 if no page matches the path.

***

# Write tools

Write tools let the assistant edit your project configuration: brands, prompts, tags, topics, products, categories, and the brand profile. Every write tool is flagged `readOnlyHint: false`, and every `delete_*` tool is flagged `destructiveHint: true`. Clients that honor MCP annotations (Claude, Cursor, and most others) prompt for explicit confirmation before the call runs. Some deletes cascade, as noted below.

Brands, prompts, tags, and topics also have **bulk variants** (`create_brands`, `update_brands`, `delete_brands`, `create_prompts`, `update_prompts`, `delete_prompts`, `create_tags`, `update_tags`, `delete_tags`, `create_topics`, `update_topics`, `delete_topics`) for handling up to 50 items in one call. Bulk tools return per-item results so partial failures don't block the rest of the batch.

Products and categories are managed only in bulk (`create_products`, `update_products`, `delete_products`, `create_categories`, `update_categories`, `delete_categories`), up to 1000 items per call.

Prompts can also be **archived** (`archive_prompt` / `unarchive_prompt`) to stop or resume running them without deleting their history.

There's also a small CRUD set for **custom domain and URL classifications** that extends the built-in classification taxonomy. Create the classification once, then assign it to specific domains or URLs as you find them.

<Note>
  All write tools except `create_projects` require organization-owner access and a `project_id`. `create_projects` needs company member access instead. Ask the assistant to look up IDs with the matching `list_*` tool before any write call so you see exactly what is about to change.
</Note>

## create\_projects

Create up to 50 projects in your company in a single call, under the same plan limits, project limit, and credit pool as creating them in the app. Each project is created or rejected on its own, so a rejected project doesn't block the rest of the batch. Your assistant confirms each project's domain and credits with you before calling.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projects` | object\[] | Yes | Up to 50 entries. Each: `name`, `domain`, `country_code`, and optionally `language_code`, `model_channel_ids`, `allocated_credits`, `timezone`, `chat_interval_weekdays`, `is_pitch`, `is_instant_pitch` |

* `allocated_credits` is required for every project except your company's first project before it has a plan, and a pitch project.
* `chat_interval_weekdays` uses ISO 8601 weekdays: 1 is Monday, 7 is Sunday.
* Only agency and partner companies can set `is_pitch`. A pitch project takes no `allocated_credits` or `model_channel_ids`, and `is_instant_pitch` requires `is_pitch`.

**Returns:** `{ created, rejected }`.

* `created`: `[{ id, name }]`
* `rejected`: `[{ name, reason }]`

***

## create\_brands

Create up to 50 brands in a single call. Duplicates (matched case-insensitively on name) are returned in `skipped` instead of failing the batch.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `brands` | object\[] | Yes | Up to 50 entries. Each: `name`, `domains`, `aliases`, `regex`, `color` |

**Returns:** `{ created, skipped }`.

* `created`: `[{ id, name }]`
* `skipped`: `[{ name, reason: "duplicate" }]`

***

## delete\_brands

Soft-delete up to 50 brands in a single call. **Destructive.**

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `brand_ids` | string\[] | Yes | Up to 50 brand IDs to delete |

**Returns:** `{ deleted, skipped }`.

* `deleted`: `[{ id }]`
* `skipped`: `[{ id, reason: "not_found" | "already_deleted" }]`

***

## update\_brands

Update up to 50 brands in a single call. Per item, set any of `name`, `regex`, `aliases`, `domains`, `color`. Changes to name, regex, or aliases trigger a background metric recalculation per brand; a brand updated mid-recalculation is rejected.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `brands` | object\[] | Yes | Up to 50 entries. Each: `brand_id` (required), `name`, `regex` (pass `null` to clear), `aliases`, `domains`, `color` |

**Returns:** `{ updatedCount, skipped, rejected }`. Successful items collapse to `updatedCount`; `skipped` and `rejected` list any items that didn't apply.

***

## create\_prompts

Create up to 50 prompts in a single call. May consume plan credits. Accepts existing `topic_id` and `tag_ids` only. This tool does not auto-create topics or tags; unknown IDs land in `rejected`.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `prompts` | object\[] | Yes | Up to 50 entries. Each: `text`, `country_code`, `topic_id`, `tag_ids` |

**Returns:** `{ created, skipped, rejected, warning? }`.

* `created`: `[{ id, text, country_code }]`
* `skipped`: `[{ text, country_code, reason: "duplicate" }]`
* `rejected`: `[{ text, country_code, reason: "limit_exceeded" | "invalid_topic" | "invalid_tag", message }]`
* `warning`: optional plan-credit warning string when the batch was partially accepted

***

## delete\_prompts

Soft-delete up to 50 prompts. **Destructive.** Each delete is enqueued asynchronously; the response reports which IDs were queued, skipped, or could not be enqueued.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `prompt_ids` | string\[] | Yes | Up to 50 prompt IDs to delete |

**Returns:** `{ queued, skipped, rejected }`.

* `queued`: `[{ id }]`
* `skipped`: `[{ id, reason: "not_found" | "already_deleted" }]`
* `rejected`: `[{ id, reason: "enqueue_failed", message }]`

***

## update\_prompts

Update the topic and/or tags of up to 50 prompts in a single call. Per item, pass `tag_ids` to fully replace the prompt's tag set, or `topic_id: null` to detach its topic. Topic and tag IDs must already exist.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `prompts` | object\[] | Yes | Up to 50 entries. Each: `prompt_id` (required), `topic_id` (or `null` to detach), `tag_ids` (replaces existing tags) |

**Returns:** `{ updatedCount, skipped, rejected }`. Successful items collapse to `updatedCount`; `skipped` and `rejected` list any items that didn't apply.

***

## archive\_prompts

Archive up to 50 prompts in one call, setting `is_archived = true` so they stop running while their chats and history stay intact. Prefer this over [`delete_prompts`](#delete-prompts) whenever the data should be kept.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `prompt_ids` | string\[] | Yes | Up to 50 prompt IDs, targeting 40 or fewer per call |

**Returns:** `{ archivedCount, skipped, rejected }`. `skipped` lists prompt IDs that weren't found.

***

## unarchive\_prompts

Unarchive up to 50 prompts, setting `is_archived = false` so they resume running.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `prompt_ids` | string\[] | Yes | Up to 50 prompt IDs, targeting 40 or fewer per call |

**Returns:** `{ unarchivedCount, skipped, rejected }`. Prompts that would take you past your plan's active-prompt limit come back under `rejected` with `plan_limit`.

***

## create\_tags

Create up to 50 tags in a single call. Duplicates (matched case-insensitively on name) land in `skipped`.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `tags` | object\[] | Yes | Up to 50 entries. Each: `name`, `color`, `group` |

**Returns:** `{ created, skipped }`.

* `created`: `[{ id, name }]`
* `skipped`: `[{ name, reason: "duplicate" }]`

***

## delete\_tags

Soft-delete up to 50 tags in a single call and detach them from every prompt they're attached to. **Destructive.**

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `tag_ids` | string\[] | Yes | Up to 50 tag IDs to delete |

**Returns:** `{ deleted, skipped }`.

* `deleted`: `[{ id }]`
* `skipped`: `[{ id, reason: "not_found" }]`

***

## update\_tags

Update up to 50 tags in a single call (name and/or color per item). System tags are skipped.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `tags` | object\[] | Yes | Up to 50 entries. Each: `tag_id` (required), `name`, `color` (from Peec's palette), `group` (set a group, `null` to ungroup, or omit to leave unchanged) |

**Returns:** `{ updatedCount, skipped, rejected }`. Successful items collapse to `updatedCount`; `skipped` (includes system tags) and `rejected` list any items that didn't apply.

***

## update\_tag\_groups

Rename or recolor up to 50 tag groups in one call. The change applies to every tag in each group.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `groups` | object\[] | Yes | Up to 50 entries. Each: `group` (the current name, required), `name` (new name), `color` (applied to every tag in the group). Provide a name, a color, or both. |

**Returns:** each updated group with its affected tag count, plus `skipped` and `rejected` items. A group with neither a new name nor a new color is rejected.

***

## delete\_tag\_groups

Delete up to 50 tag groups. By default each group's tags survive and are simply ungrouped.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `groups` | object\[] | Yes | Up to 50 entries. Each: `group` (the name to delete, required), `delete_tags` (default `false`) |

**Returns:** each group with its affected tag count, plus `skipped` and `rejected` items.

<Info>
  Setting `delete_tags: true` deletes the group's tags outright and detaches them from every prompt, which can't be undone. Leave it `false` to keep the tags and only drop the grouping.
</Info>

***

## create\_topics

Create up to 50 topics in a single call. Duplicates (matched case-insensitively on name) land in `skipped`. Items beyond the project's topic limit land in `rejected`.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `topics` | object\[] | Yes | Up to 50 entries. Each: `name` (1-64 chars), `country_code` |

**Returns:** `{ created, skipped, rejected }`.

* `created`: `[{ id, name }]`
* `skipped`: `[{ name, reason: "duplicate" }]`
* `rejected`: `[{ name, reason: "limit_exceeded", message }]`

***

## delete\_topics

Soft-delete up to 50 topics in a single call. **Destructive.** Associated prompts are detached (not deleted); any AI-generated prompt suggestions under the topics are deleted.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `topic_ids` | string\[] | Yes | Up to 50 topic IDs to delete |

**Returns:** `{ deleted, skipped }`.

* `deleted`: `[{ id }]`
* `skipped`: `[{ id, reason: "not_found" | "already_deleted" }]`

***

## update\_topics

Rename up to 50 topics in a single call.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `topics` | object\[] | Yes | Up to 50 entries. Each: `topic_id` (required), `name` (1–64 characters) |

**Returns:** `{ updatedCount, skipped, rejected }`. Successful items collapse to `updatedCount`; `skipped` and `rejected` list any items that didn't apply.

***

## generate\_topics

Composes candidate topics for your project from its Brand Profile, the same composition [Prompt discovery](/setting-up-your-prompts#option-4-prompt-discovery) runs in the app.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `topic_count` | number | No | How many topics to compose, 1 to 50. Defaults to the number your plan allows. |

**Returns:** `{ topics: [name, ...] }`.

Nothing is saved. Review the returned names, then create the ones you want with [`create_topics`](#create-topics). Composition already accounts for your existing topics, so it proposes only what fills a gap and can come back empty when your set is already well covered.

<Info>
  Needs the Brand Profile to name your products and services, which you set with [`set_project_profile`](#set-project-profile). It spends one of the project's hourly topic generations, so it's never called in a loop.
</Info>

***

## generate\_prompt\_suggestions

Generates prompt suggestions for your project, the same generation [Prompt discovery](/setting-up-your-prompts#option-4-prompt-discovery) runs in the app. Generation happens in the background.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `topic_id` | string | No | Generate for this topic alone instead of every topic awaiting review, replacing the suggestions it already has |
| `prompt_suggestion_id` | string | No | Replace this one suggestion, keeping its ID, topic and market |
| `segment` | object | No | Add suggestions for one slice of a topic, keeping the ones it already has. Takes `topic_id` (required), plus `branding`, `intent`, `persona_tag_id`, `country` and `count`. Any dimension you leave unset is filled from your target distribution and markets. |

**Returns:** `{ queued: true, generation_id }`. Poll it with [`get_prompt_suggestion_generation`](#get-prompt-suggestion-generation), then read the results with [`list_prompt_suggestions`](#list-prompt-suggestions) and resolve them with [`finalize_prompt_suggestions`](#finalize-prompt-suggestions).

`topic_id`, `prompt_suggestion_id` and `segment` are mutually exclusive and each narrow the run. With none of them, every topic awaiting review is generated for again and its current suggestions are replaced, so pass a scope unless you actually want a full refresh.

<Info>
  Needs `prompt_builder.distribution`, the branding and intent split, set through [`set_project_profile`](#set-project-profile). Markets are optional: without them your own country and language are used. It spends one of the project's hourly prompt generations, so it's never called in a loop.
</Info>

***

## update\_prompt\_suggestions

Edit up to 50 pending suggestions before you finalize them: rewrite the text, replace the tag set, or both. Prefer this over rejecting and regenerating when a suggestion is close but not quite right.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `suggestions` | object\[] | Yes | Up to 50 entries. Each: `prompt_suggestion_id` (required), `text`, `tag_ids`. |

**Returns:** `{ updatedCount, skipped, rejected }`. Successful items aren't echoed back.

Editing keeps a suggestion pending, so accept it with [`finalize_prompt_suggestions`](#finalize-prompt-suggestions) to create the tracked prompt. `tag_ids` fully replaces the item's tags and must be existing IDs from [`list_tags`](#list-tags); system tags keep at most one per group, and the last one passed wins.

***

## finalize\_prompt\_suggestions

Resolves prompt suggestions in one pass over a reviewed set. IDs in `accepted_ids` become tracked prompts and promote their topics into the project; IDs in `rejected_ids` are deleted from the review list.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `accepted_ids` | string\[] | No | Suggestion IDs to turn into tracked prompts |
| `rejected_ids` | string\[] | No | Suggestion IDs to delete from the review list |

Pass either or both, up to 50 IDs across the two lists, targeting 40 or fewer per call. At least one ID is required.

**Returns:** a count per outcome, any IDs that matched no suggestion, and any allowance warning.

Rejecting never touches your tracked prompts, since a suggestion has produced none until it's accepted. A topic left with no suggestions is cleared along with them.

<Info>
  The accepted set is checked against your project's remaining prompt allowance as a whole and refused as a batch when it doesn't fit. Trim it and retry rather than splitting it across calls, and note that a refused accept also leaves the rejections unapplied.
</Info>

***

## create\_global\_brand

Creates a brand in the shopping catalog and returns its `global_brand_id`. Use it when [`list_global_brands`](#list-global-brands) finds no match for a brand you need, or when [`create_products`](#create-products) rejects an item with `brand_not_found`.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `name` | string | Yes | The brand name |

**Returns:** `{ id, name }`. The returned name is the brand's canonical name and can differ slightly from the one you sent.

<Info>
  This is separate from [`create_brands`](#create-brands), which creates the brands a project tracks for AI-visibility reporting. The two carry different IDs and aren't interchangeable.
</Info>

***

## create\_products

Create products in a project. Up to 1000 per call. Each product needs a `global_brand_id` (resolve via [`list_global_brands`](#list-global-brands)) and a `name` unique within that brand.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `products` | object\[] | Yes | Up to 1000 entries. Each: `global_brand_id` (required), `name` (required), `description`, `image_url`, `price_override` (per-currency min/max), `category_ids` |

**Returns:** `{ created, rejected }` per item. Rejection reasons: `name_conflict`, `brand_not_found`, `category_not_found`.

***

## update\_products

Update products by id (resolve via [`list_products`](#list-products)). Up to 1000 per call. Per item, set any of `name` (unique within the brand), `description`, `image_url`, `price_override` (replaces all overrides; `{}` clears them), `category_ids` (replaces the product's categories; `[]` uncategorizes). Omitted fields are left unchanged.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `products` | object\[] | Yes | Up to 1000 entries. Each: `product_id` (required) plus the fields to change |

**Returns:** `{ updated, skipped, rejected }` per item. An item with nothing to apply is skipped; an unsatisfiable change (name conflict, unknown category) is rejected.

***

## delete\_products

Delete products by id. **Destructive.** Up to 1000 per call.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `product_ids` | string\[] | Yes | Up to 1000 product IDs |

**Returns:** `{ deleted, skipped }` per item (`skipped` reason: `not_found`).

***

## create\_categories

Create product categories. Up to 1000 per call, applied in order. Each needs a `name` and an optional `parent_id` — omit it for a top-level category, or pass another category's id to nest it underneath. A name must be unique among its siblings.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `categories` | object\[] | Yes | Up to 1000 entries. Each: `name` (required), `parent_id` (optional) |

**Returns:** `{ created, rejected }` per item. Rejection reasons: `parent_not_found`, `name_conflict`.

***

## update\_categories

Rename and/or move categories by id (resolve via [`list_categories`](#list-categories)). Up to 1000 per call. Each item sets `name` (rename), `parent_id` (move under that category, or `null` to promote to the top level), or both.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `categories` | object\[] | Yes | Up to 1000 entries. Each: `category_id` (required), `name`, `parent_id` |

**Returns:** `{ updated, rejected }` per item. Rejection reasons: `not_found`, `name_conflict`, `invalid_move` (nesting a category inside itself).

***

## delete\_categories

Delete categories by id. **Destructive.** Up to 1000 per call. A deleted category's children and products move up to its parent — a top-level delete sends children to the top level and its products to Uncategorized.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `category_ids` | string\[] | Yes | Up to 1000 category IDs |

**Returns:** `{ deleted, rejected }` per item. Rejection reasons: `not_found`, `name_conflict` (a child moved up would clash with an existing sibling name).

***

## create\_domain\_classification

Define a new custom domain classification entity on a project. This creates the classification but does **not** assign it to any domain — use [`assign_domain_classification`](#assign-domain-classification) for that.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `name` | string | Yes | Classification name (unique per project) |
| `color` | string | No | Display color from Peec's palette |

**Returns:** `{ id }`.

***

## delete\_domain\_classification

Permanently delete a custom domain classification entity. **Destructive.** Cascades through the override table — any domain currently assigned this classification falls back to its heuristic classification. To clear a single domain instead, use [`unassign_domain_classification`](#unassign-domain-classification).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `name` | string | Yes | Name of the custom domain classification to delete |

**Returns:** `{ success: true }`.

***

## assign\_domain\_classification

Assign a built-in classification (`Corporate`, `Competitor`, `Editorial`, `Institutional`, `Other`, `Reference`, `UGC`, `You`, `Related`) or the name of a custom domain classification to a domain. Overrides any heuristic classification. The override applies at apex granularity.

If a display label collides with an existing custom classification name, the custom classification wins — pass the built-in enum value (e.g. `OTHER`) to force the built-in.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `domain` | string | Yes | Domain to classify (any host or apex — applied at apex granularity) |
| `classification` | string | Yes | Built-in classification display name or custom classification name |

**Returns:** `{ success: true }`.

***

## unassign\_domain\_classification

Clear the classification override on a domain, restoring its heuristic classification. Does **not** delete the custom classification entity itself.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `domain` | string | Yes | Domain whose classification override should be cleared |

**Returns:** `{ success: true }`.

***

## create\_url\_classification

Define a new custom URL classification entity on a project. This creates the classification but does **not** assign it to any URL — use [`assign_url_classification`](#assign-url-classification) for that.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `name` | string | Yes | Classification name (unique per project) |
| `color` | string | No | Display color from Peec's palette |

**Returns:** `{ id }`.

***

## delete\_url\_classification

Permanently delete a custom URL classification entity. **Destructive.** Cascades through the override table — any URL currently assigned this classification falls back to its heuristic classification. To clear a single URL instead, use [`unassign_url_classification`](#unassign-url-classification).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `name` | string | Yes | Name of the custom URL classification to delete |

**Returns:** `{ success: true }`.

***

## assign\_url\_classification

Assign a built-in classification (`Homepage`, `Category Page`, `Product Page`, `Listicle`, `Comparison`, `Profile`, `Alternative`, `Discussion`, `How-To Guide`, `Article`, `Other`) or the name of a custom URL classification to a URL. Overrides any heuristic classification. The override applies to the normalized URL form.

If a display label collides with an existing custom classification name, the custom classification wins — pass the built-in enum value (e.g. `OTHER`) to force the built-in.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `url` | string | Yes | URL to classify |
| `classification` | string | Yes | Built-in classification display name or custom classification name |

**Returns:** `{ success: true }`.

***

## unassign\_url\_classification

Clear the classification override on a URL, restoring its heuristic classification. Does **not** delete the custom classification entity itself.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `url` | string | Yes | URL whose classification override should be cleared |

**Returns:** `{ success: true }`.

***

## create\_facts

Adds up to 50 manual facts in one call. Each fact is a statement about your brand that Peec checks claims from AI answers against.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `facts` | object\[] | Yes | Up to 50 entries, targeting 40 or fewer per call. Each: `text`, the statement to check claims against. |

**Returns:** every created fact with its new ID.

***

## update\_facts

Updates the wording or the active state of up to 50 facts.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `facts` | object\[] | Yes | Up to 50 entries. Each: `fact_id` (required), `text`, `is_active`. Provide `text`, `is_active`, or both. |

**Returns:** `{ updatedCount, skipped, rejected }`.

Changing `text` creates a new version and preserves the old wording for verdicts already reached. Setting `is_active: false` keeps the fact visible but leaves it out of future fact-checking, so it parks a fact without deleting it.

***

## delete\_facts

Deletes up to 50 facts. Deleted facts disappear from the fact list and are left out of future fact-checking, while verdicts already reached keep their original fact versions.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `fact_ids` | string\[] | Yes | Up to 50 fact IDs, copied verbatim from [`list_facts`](#list-facts) |

**Returns:** `{ deletedCount, skipped }`.

<Info>
  Deletion is a soft delete, but the Peec app has no undo for it. Your assistant reads the exact statements back to you before calling.
</Info>

***

## edit\_brand\_perception\_attribute\_clusters

Renames, deletes and reassigns Brand Perception attribute clusters, the same edits the Manage attributes screen makes. Use it when an attribute is mislabeled, duplicated or split across two clusters.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `renames` | object\[] | No | Up to 50 entries. Each: `cluster_id` and a new `name`, unique within the project case-insensitively. The cluster keeps its ID and its history, so scores blend across the rename. |
| `delete_cluster_ids` | string\[] | No | Up to 50 clusters to remove. Each must hold no attributes by the time it's deleted. |
| `reassignments` | object\[] | No | Up to 200 entries. Each: `attribute`, spelled exactly as the listing returns it, and the `cluster_id` it moves into. Works for attributes listed under `unassigned` too. |

Pass any combination, and at least one. Resolve every `cluster_id` and attribute with [`list_brand_perception_attribute_clusters`](#list-brand-perception-attribute-clusters) first, and copy both verbatim.

**Returns:** the counts applied. Errors come back as `invalid` (a repeated target), `not_found` (unknown cluster or attribute), or `conflict` (a new label collides with another cluster, or a deleted cluster still holds attributes).

The whole call is one transaction, so if any edit is rejected nothing is applied. Edits run in the order reassign, rename, delete however you list them, which makes merging two clusters a single call: reassign every attribute out of the losing cluster, then delete it. Name each attribute and each cluster at most once per call, since two edits naming the same one would conflict.

<Info>
  Scores re-aggregate on the next read, so the change is immediate and needs no new run. It rewrites a taxonomy the whole project shares and there's no undo, so your assistant shows you the exact edits and waits for your confirmation.
</Info>

***

## update\_actions\_status

Moves up to 50 actions to a status, the same ones the Actions page writes: `ACCEPTED` to take one on, `REJECTED` to decline it, `COMPLETED` to record that the work is done, `PENDING` to put a resolved action back on the undecided pile, `DELETED` to take it off the list altogether.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `action_ids` | string\[] | Yes | Up to 50 action IDs, copied verbatim from [`list_actions`](#list-actions) |
| `status` | string | Yes | The status to move every listed action to |

**Returns:** a count of updated actions plus `skipped` and `rejected` items.

Complete an action only once the change is actually live on the page. The status is what tells everyone where the work stands, and it doesn't itself affect visibility. An action that's already deleted reads as absent, so a second call naming one comes back skipped. A `CONTENT_OPTIMISATION` action can only be updated when **Content optimization** is enabled for the project. Otherwise it comes back skipped, as an action the project doesn't have.

***

## update\_action\_steps

Records which of an action's steps you've done, across up to 50 actions in one call.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `actions` | object\[] | Yes | Up to 50 entries, targeting 40 or fewer per call. Each names one action and either sets `completed` for every step it holds, or lists `steps`. |

Each step in turn either sets `completed` for all of its options or names `options` individually, each with its own `completed`, so one call can tick some and untick others. Setting `completed` and listing parts at the same level is rejected. Passing `false` puts a step or option back to not-done, so a step marked off by mistake can be corrected.

**Returns:** `updatedCount` plus `skipped` and `rejected` items, keyed on `action_id`.

| Outcome | Meaning |
| - | - |
| `not_found` | No such action in this project |
| `step_not_found` / `option_not_found` | Usually an ID from before Peec regenerated the action. Read it again. |
| `duplicate_id` / `duplicate_step_id` | The same action, or the same step within one action, appears more than once in this call |
| `not_completable` | The action is a content brief, whose steps are the material it was written from rather than work to do |

An action is all or nothing: anything that can't be applied leaves every step on it untouched, so you never have to read an action back to find out what landed. Other actions in the same call still go through. A `CONTENT_OPTIMISATION` action can only be updated when **Content optimization** is enabled for the project. Otherwise it comes back skipped.

<Info>
  Read the step and option IDs with [`get_action`](#get-action) and `fields: ["steps"]` first. They aren't in [`list_actions`](#list-actions), and an ID from an earlier read can be stale.

  <br />

  <br />

  This records work you've already finished. It does nothing to the pages the engines read, and completing every step doesn't move the action to `COMPLETED`. The action's own status changes in the Peec app or through [`update_actions_status`](#update-actions-status).
</Info>

***

## create\_actions

Writes up to 50 actions of your own in one call, so work Peec didn't suggest is tracked beside the work it did, with the same list, statuses, and filters.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `actions` | object\[] | Yes | Up to 50 actions, targeting 40 or fewer per call |

Each action takes:

| Field | Required | Description |
| - | - | - |
| `title` | Yes | Up to 250 characters |
| `kind` | Yes | What the work is, which decides the action's type and group: `CONTENT_OPTIMIZATION` (Content optimization), `CONTENT_CREATION` (Create content), `MENTION` (Improve a mention), `TECHNICAL` (Fix a technical issue), `PRODUCT_PAGE` (Improve a product page), or `OTHER` (Something else) |
| `status` | No | Where the action starts: `PENDING` (default), `ACCEPTED`, `COMPLETED`, or `REJECTED` |
| `page_url` | No | The page the action lands on. On an owned-page kind, it's also the page the action is measured against. |
| `description` | No | `{ text, html? }`. What the action is for. |
| `notes` | No | `{ text, html? }`. Working notes kept beside the action. |
| `steps` | No | The work to do. Each step has a `title`, and optionally a `description`, `completed`, and a `section` heading to group it under. |
| `topic_id` | No | Topic the action is scoped to (from [`list_topics`](#list-topics)) |
| `prompt_ids` | No | Prompts the action is meant to move (from [`list_prompts`](#list-prompts)) |
| `priority` | No | `none`, `low`, `medium`, or `high`. It fills the same impact bars a generated action fills, so the two sort together. |
| `country_codes` | No | ISO 3166-1 alpha-2 markets. Omit for every market the project tracks. |
| `language_codes` | No | Languages the action is scoped to |
| `tag_ids` | No | Tags to file the action under |
| `category` | No | Free-form category |
| `assignee_user_id` | No | The project member who owns the work |
| `due_on` | No | Calendar day in the project's timezone (`YYYY-MM-DD`) |
| `repeat` | No | `{ every, unit }`, where `every` is 1 to 12 and `unit` is `day`, `week`, `month`, or `year` |
| `time_range` | No | The window the action's measurements are read over: `7d`, `28d`, `90d`, or `all` |

**Returns:** `created` (each with its `index`, new `action_id`, and `title`) plus any `rejected` items. A topic or prompt the project doesn't have rejects that item alone.

Writing an action records an intention. It doesn't change what AI engines say, and it doesn't make Peec do the work.

***

## update\_actions

Rewrites the fields you own on up to 50 actions. It works on actions you wrote and on ones Peec generated. Your edit is kept beside Peec's wording rather than replacing it, so a later regeneration can't discard it.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `actions` | object\[] | Yes | Up to 50 entries, targeting 40 or fewer per call. Each has an `action_id` (from [`list_actions`](#list-actions)) plus any of the fields [`create_actions`](#create-actions) accepts, except `status`. |

A field you leave out keeps its value, and `null` clears the fields that can be cleared. An entry with no field besides its `action_id` is rejected. `steps` and `prompt_ids` replace the whole list rather than merging into it. To tick off a step without rewriting the list, use [`update_action_steps`](#update-action-steps). To change status, use [`update_actions_status`](#update-actions-status).

Only an action you wrote can change `kind`. A generated action keeps the type and group Peec found it under, and an entry that tries to change them is rejected.

**Returns:** a count of updated actions plus `skipped` (`not_found`) and `rejected` (`duplicate_id`, `no_change`, or `invalid`) items.

A `CONTENT_OPTIMISATION` action can only be updated when **Content optimization** is enabled for the project. Otherwise it comes back skipped.

***

## delete\_actions

Permanently removes up to 50 actions you wrote yourself. **Destructive.** There's no way to restore a deleted action.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `action_ids` | string\[] | Yes | Up to 50 action IDs, copied verbatim from [`list_actions`](#list-actions) |

**Returns:** a count of deleted actions plus `skipped` items.

An action Peec generated can't be deleted here, and comes back skipped just like a missing one. Decline it with [`update_actions_status`](#update-actions-status) instead, which keeps a record of what was suggested.

***

## resolve\_optimize\_content\_suggestions

Accepts, dismisses, or reverts suggestions on a `CONTENT_OPTIMISATION` action, up to 50 in one call. This is the same change you make with **Apply**, **Dismiss**, and **Revert** on the Optimize content screen. Only available when **Content optimization** is enabled for the project.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `action_id` | string | Yes | The ID of a `CONTENT_OPTIMISATION` action, copied verbatim from [`list_actions`](#list-actions) |
| `suggestion_ids` | string\[] | Yes | Up to 50 suggestion IDs from [`get_optimize_content`](#get-optimize-content), targeting 40 or fewer per call |
| `action` | string | Yes | Applied to every ID in the call: `accept`, `reject`, or `revert` |

| `action` | Effect |
| - | - |
| `accept` | Takes a `rewrite` suggestion's wording into the article. Accepting an `edit`, which carries no wording, marks it resolved without changing a word. |
| `reject` | Dismisses the suggestion and keeps the original wording |
| `revert` | Puts an accepted or dismissed suggestion back to pending. Only works on suggestions Peec generated. An edit you typed yourself is undone in the editor, so reverting one is an error. |

**Returns:** `score` (the optimization score out of 100 after the change), `unchanged`, and `suggestions` (each ID's resulting `state`).

Every change in the call lands in one revision of the article, under your name in its history. An ID already in the requested state is left alone and counted in `unchanged`. An ID that isn't on this action is an error, and nothing is written.

<Tip>
  This doesn't return the new wording. Read the article again with [`get_optimize_content`](#get-optimize-content) to see it.
</Tip>

***

## edit\_optimize\_content

Rewrites passages of the article behind a `CONTENT_OPTIMISATION` action, up to 50 in one call. Only available when **Content optimization** is enabled for the project.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `action_id` | string | Yes | The ID of a `CONTENT_OPTIMISATION` action, copied verbatim from [`list_actions`](#list-actions) |
| `edits` | object\[] | Yes | Up to 50 passages to rewrite, targeting 40 or fewer per call |

Each edit takes:

| Field | Required | Description |
| - | - | - |
| `original_text` | Yes | The passage as it currently reads, quoted word for word from the `article` that [`get_optimize_content`](#get-optimize-content) returns. Quote one whole paragraph or heading, not a fragment. |
| `new_text` | Yes | The replacement, as markdown. It can't be empty, so this tool rewrites passages but can't delete them. |
| `carries_out_suggestion_id` | No | The ID of the `edit` suggestion this rewrite carries out. It's marked accepted in the same revision. |

**Returns:** `score` (the optimization score out of 100 after the change), `edited` (how many passages were rewritten), `carried_out` (how many `edit` suggestions were marked accepted), and `suggestion_ids` (the tracked edits this call created).

Every edit lands in one revision, and nothing is written unless all of them apply. The whole call fails if a quote matches no passage or several, or if two edits target the same passage. If the article changed since you read it, the edit is rejected rather than applied over, so read it again before retrying.

Changes appear as tracked edits under your name. You can revert them on the Optimize content screen just like edits you typed.

***

## set\_project\_profile

Replace the project's brand profile. Every field is required, so call [`get_project_profile`](#get-project-profile) first, merge your changes into the existing values, then send the complete profile here. Saving triggers a background refresh of the project's prompt suggestions. The project display name is not part of the profile and can't be changed via this tool.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `occupation` | string | Yes | Short brand description used in every generated prompt. Be specific. |
| `industry` | string | Yes | Industry or vertical (e.g. `FinTech`, `E-commerce`) |
| `brandPresentation` | string\[] | Yes | Adjectives that define the brand's positioning (e.g. `premium`, `challenger`) |
| `productsAndServices` | string\[] | Yes | Main product lines, service categories, or flagship offerings |
| `targetMarkets` | object\[] | Yes | Geographic scope. Each entry: `{ marketSize, location, osmId? }` |
| `audienceDistribution` | object | Yes | `{ simpleRecommendationSeeker, informedShopper, evaluativeResearcher }` integers that must sum to 100 |

`marketSize` is one of: `Neighborhood`, `City`, `State/Province`, `National`, `Continental Bloc`, `Global`.

**Returns:** `{ success: true }`.

***

## list\_facts

List the facts a project checks claims against. Manual facts were added by a person, website facts were extracted from the project's site. An inactive fact stays in the list but is left out of future fact-checking, and soft-deleted facts are never returned. Call this to resolve fact IDs before [`update_facts`](#update-facts) or [`delete_facts`](#delete-facts).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `origin` | string | No | `manual` or `website` |
| `is_active` | boolean | No | Filter by whether the fact is used in future fact-checking |
| `fields` | string\[] | No | Subset of the columns below |
| `limit` | number | No | Max facts to return (default 100, max 1000) |
| `offset` | number | No | Facts to skip, for paging |

**Returns:** columnar JSON `{ columns, rows, rowCount, totalCount, fact_limit, active_fact_count }`, newest first. Columns: `id`, `text`, `origin`, `is_active`, `edited_at`, `created_at`.

`fact_limit` is how many active facts the project's plan allows, and `null` means unlimited. `active_fact_count` is how many it holds now, so the difference is the room left before [`create_facts`](#create-facts) is rejected.

***

## create\_facts

Add up to 50 manual facts in one call. Each fact is a statement about the brand that Peec checks claims in future AI answers against. Confirm the exact statements with the user first, because this changes shared project data.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `facts` | object\[] | Yes | Up to 50 entries (aim for 40 or fewer per call), each `{ text }`, e.g. `[{"text":"Plans start at €99 per month."}]` |

**Returns:** `{ created, skipped?, rejected? }`. Created facts come back in full with their new IDs.

***

## update\_facts

Update the wording or the active state of up to 50 facts in one call. Changing the text creates a new version and keeps the old wording on the verdicts already given against it. Setting `is_active` to false keeps the fact but leaves it out of future fact-checking.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `facts` | object\[] | Yes | Up to 50 entries. Each: `fact_id` (required), and `text`, `is_active`, or both |

**Returns:** `{ updatedCount, skipped?, rejected? }`.

***

## delete\_facts

Soft-delete up to 50 facts. **Destructive.** Deleted facts leave the fact list and future fact-checking; verdicts already given keep the fact version they were judged against. There is no undo in the Peec app, so show the user the exact statements first.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | The project ID |
| `fact_ids` | string\[] | Yes | Up to 50 fact IDs, copied verbatim from [`list_facts`](#list-facts) |

**Returns:** `{ deletedCount, skipped? }`.

<Info>
  The fact tools appear only on projects with fact-checking enabled. Writing facts also requires owner access to the project, while `list_facts` is available to any viewer.
</Info>

***

# Report filters and dimensions

## Filtering

The three report tools support filters to narrow results. Each filter looks like this:

```json theme={null}
{
  "field": "model_channel_id",
  "operator": "in",
  "values": ["openai-0", "perplexity-0"]
}
```

### Standard filter fields

These all use `in` / `not_in` operators with a `values` array.

| Field | Available in | Description |
| - | - | - |
| `model_id` | All reports | **Deprecated** — prefer `model_channel_id`. AI search engine (e.g. `chatgpt-scraper`, `perplexity-scraper`, `gemini-scraper`). Call `list_models` to get the IDs available for your project. |
| `model_channel_id` | All reports | Stable engine channel ID — survives model version upgrades. Call [`list_model_channels`](#list-model-channels) to resolve. |
| `topic_id` | All reports | Topic grouping ID |
| `tag_id` | All reports | Tag ID |
| `prompt_id` | All reports | Individual prompt ID |
| `country_code` | All reports | ISO 3166-1 alpha-2 code (e.g. `US`, `DE`, `GB`) |
| `brand_id` | Brand report | Brand ID |
| `domain` | Domain and URL reports | Domain name |
| `url` | Domain and URL reports | Full URL |
| `chat_id` | All reports | Individual chat/conversation ID |
| `mentioned_brand_id` | Domain and URL reports | Only sources where this brand was mentioned |
| `domain_classification` | Domain and URL reports | Built-in classification display name (`Corporate`, `Editorial`, ...) or the name of a custom domain classification. See [`list_domain_classifications`](#list-domain-classifications). |
| `url_classification` | URL report | Built-in classification display name (`Listicle`, `Comparison`, ...) or the name of a custom URL classification. See [`list_url_classifications`](#list-url-classifications). |

### Numeric filters

Domain and URL reports also accept two numeric filters. These use `gt` / `gte` / `lt` / `lte` operators with a single `value` (not `values`).

**`mentioned_brand_count`**: filter by number of unique brands mentioned alongside a source.

```json theme={null}
{
  "field": "mentioned_brand_count",
  "operator": "gte",
  "value": 2
}
```

**`gap`**: gap analysis. Excludes sources where your own brand is mentioned, then filters by how many competitor brands are present. This is Peec's most actionable competitive filter: it finds content where competitors appear but you don't.

```json theme={null}
{
  "field": "gap",
  "operator": "gte",
  "value": 2
}
```

The example above returns domains or URLs where the own brand is absent but at least 2 competitors are mentioned.

### Operators

| Operator | Use with | Description |
| - | - | - |
| `in` | Standard fields | Include only matching values |
| `not_in` | Standard fields | Exclude matching values |
| `gt`, `gte`, `lt`, `lte` | `mentioned_brand_count`, `gap` | Numeric comparisons |

You can combine multiple filters. They're joined with AND logic.

## Sorting

The three report tools accept an `order_by` array that sorts results before pagination. Each entry is `{ field, direction }`. `direction` is `asc` or `desc` and defaults to `desc`. Multiple entries create a multi-key sort, applied in order.

```json theme={null}
[
  { "field": "visibility", "direction": "desc" },
  { "field": "mention_count", "direction": "desc" }
]
```

Sortable fields by report:

| Report | Sortable fields |
| - | - |
| `get_brand_report` | `visibility`, `visibility_count`, `mention_count`, `sentiment`, `position`, `share_of_voice` |
| `get_domain_report` | `citation_rate`, `retrieval_count`, `citation_count` |
| `get_url_report` | `retrievals`, `retrieval_count`, `citation_count`, `citation_rate` |

When `order_by` is omitted, each report falls back to a sensible default ordering.

## Dimensions

Dimensions break down results into rows grouped by a specific field. Without dimensions, results are totals for the entire date range.

| Dimension | What it does | When to use it |
| - | - | - |
| `date` | Daily breakdown (YYYY-MM-DD) | Tracking trends over time |
| `model_id` | Per AI search engine (deprecated, prefer `model_channel_id`) | Comparing performance across ChatGPT, Perplexity, etc. |
| `model_channel_id` | Per stable engine channel | Same as `model_id` but survives model version changes |
| `topic_id` | Per topic grouping | Finding your strongest and weakest topic areas |
| `tag_id` | Per tag | Analyzing custom segments |
| `prompt_id` | Per individual prompt | Drilling into specific queries |
| `country_code` | Per country | Checking geographic differences |
| `chat_id` | Per individual AI conversation | Inspecting specific responses |

You can combine dimensions. For example, `["date", "model_channel_id"]` gives you daily trends per AI engine.


# Use Cases
Source: https://docs.peec.ai/mcp/use-cases

Example prompts and workflows for the Peec AI MCP Server. Browse by type if you need ideas on what to ask.

Start by asking your AI assistant to list your projects, then pick one:

> *"List my Peec AI projects"*

<Tip>
  Include a time range in your questions. *"Last 30 days"*, *"this month"*, or *"past week"* gets you better results.
</Tip>

<Note>
  For the most common workflows (weekly pulse, competitor radar, engine scorecard, source audit, campaign tracker), use a built-in [prompt](/mcp/prompts) instead. One slash command runs the full analysis and formats the output.
</Note>

## Example workflows

### 1. Brand visibility overview

> *"How visible is my brand across AI search engines this month?"*

Returns your visibility percentage, sentiment score, share of voice, and average position across all tracked AI models.

### 2. Competitive benchmarking by AI model

> *"Compare our visibility against competitors, broken down by AI model"*

Table showing each brand's visibility across ChatGPT, Perplexity, Gemini, and other platforms. See where you lead and where competitors outperform you.

### 3. Source citation analysis

> *"Which of our pages get cited most by AI engines?"*

Ranked list of your URLs with citation counts, retrieval numbers, and page types.

### 4. Topic deep-dive

> *"How do we perform on the topic 'sustainable fashion' vs competitors?"*

Brand-by-brand comparison within a specific topic: visibility, share of voice, and sentiment.

### 5. Visibility trend

> *"Show me our visibility trend over the last 30 days"*

Daily visibility data with notable changes highlighted.

## More ideas

### Brand visibility

<AccordionGroup>
  <Accordion title="Visibility by AI model">
    > *"Break down our brand visibility by AI model for the past two weeks."*

    Get an overview of your performance for each AI model.
  </Accordion>

  <Accordion title="Topic-level performance">
    > *"Which topics have the highest and lowest visibility for our brand?"*

    Identify the strengths and weaknesses in your AI search presence.
  </Accordion>
</AccordionGroup>

### Competitive analysis

<AccordionGroup>
  <Accordion title="Share of voice comparison">
    > *"Compare our share of voice against all competitors for the last month."*

    Your mention share vs the competitive set.
  </Accordion>

  <Accordion title="Sentiment comparison">
    > *"How does our sentiment compare to \[competitor name] on ChatGPT?"*

    Find out how positively AI models describe you vs a specific competitor.
  </Accordion>

  <Accordion title="Position analysis">
    > *"Which competitor is mentioned first most often across all AI models?"*

    Understand who consistently wins the top position in AI responses.
  </Accordion>
</AccordionGroup>

### Sources and citations

<AccordionGroup>
  <Accordion title="Top cited domains">
    > *"What are the most cited domains in AI responses for our prompts?"*

    Use this to understand which websites have the most authority in your space.
  </Accordion>

  <Accordion title="Your domain's performance">
    > *"How often is our website retrieved and cited? Break it down by AI model."*

    You can make these kinds of queries to gain an idea of how your domain's source authority is across AI platforms.
  </Accordion>

  <Accordion title="Competitor source analysis">
    > *"Which competitor domains have the highest citation rate?"*

    Find out which competitor websites AI treats as authoritative.
  </Accordion>

  <Accordion title="Inspect why a URL wins citations">
    > *"Pull the content of the top-cited competitor URL on the topic 'project management tools' and tell me what it covers that our own page doesn't."*

    The MCP fetches the scraped markdown of the source Peec has indexed, so your AI assistant can compare structure, depth, and framing against your own content.
  </Accordion>
</AccordionGroup>

### Reporting

<AccordionGroup>
  <Accordion title="Weekly performance summary">
    > *"Give me a weekly summary: our visibility, share of voice, and sentiment for the past 7 days vs the previous 7 days."*

    A quick health check you can run every week.
  </Accordion>

  <Accordion title="Country-level breakdown">
    > *"Break down our visibility by country for the last month."*

    Understand the geographic differences in your AI search presence if you have prompts in multiple markets.
  </Accordion>

  <Accordion title="Content gap analysis">
    > *"Which topics have high competitor visibility but low visibility for our brand?"*

    Find opportunities where competitors are visible, but you're not.
  </Accordion>
</AccordionGroup>

### Actions and next steps

<AccordionGroup>
  <Accordion title="Ranked next steps for the quarter">
    > *"What should we focus on next quarter to improve AI visibility?"*

    Returns Peec's opportunity-scored recommendations grouped by owned pages, editorial coverage, reference sites, and UGC communities. No invented advice. Rankings are computed from your actual visibility gaps.
  </Accordion>

  <Accordion title="Drill into a specific opportunity">
    > *"Our biggest opportunity is UGC on YouTube. What specifically should we do there?"*

    The MCP first calls the actions overview to surface the opportunity, then drills into the UGC domain with concrete outreach suggestions (creators to contact, formats that work).
  </Accordion>
</AccordionGroup>

### Agent analytics

Pair these with [Crawl Insights](/crawl-insights). The MCP exposes the same access-log data via [`list_bots`](/mcp/tools#list-bots) and [`get_agent_visits`](/mcp/tools#get-agent-visits), so an assistant can answer ad-hoc questions without leaving the chat.

<AccordionGroup>
  <Accordion title="Which AI bots are hitting our site?">
    > *"Break down AI bot visits to our site by bot for the last 30 days."*

    Returns a ranked list of bots (`GPTBot`, `ClaudeBot`, `PerplexityBot`, ...) with visit counts. Group by `bot_id` to see who's crawling you most.
  </Accordion>

  <Accordion title="What's our failure rate for AI bots?">
    > *"Group AI bot visits by response status for the last 7 days. Show me the share of 4xx and 5xx."*

    Surfaces non-200 responses bots received. High shares of `403`, `404`, or `5xx` codes are a signal that crawlers can't reach the content you want indexed.
  </Accordion>

  <Accordion title="Which folders are bots crawling most?">
    > *"For the last 30 days, group AI bot visits by request path. Which sections of the site get the most attention?"*

    Returns paths sorted by visit count. Useful for confirming whether bots are spending time on the pages you most care about ranking in AI responses.
  </Accordion>

  <Accordion title="Has crawl activity changed over time?">
    > *"Show me daily AI bot visits over the last 90 days. Highlight any drops or spikes."*

    Uses `time_bucket=day` to return a daily series. Pair with bot grouping to see whether one vendor is responsible for a change.
  </Accordion>

  <Accordion title="Tie bot traffic to AI visibility">
    > *"For the top 20 URLs by AI bot visits last month, also pull their retrieval and citation counts as AI sources."*

    Combines [`get_agent_visits`](/mcp/tools#get-agent-visits) grouped by `request_path` with [`get_url_report`](/mcp/tools#get-url-report). Surfaces whether the pages bots crawl most are the same pages winning AI citations.
  </Accordion>
</AccordionGroup>

### Shopping

For [shopping projects](/setting-up-shopping-prompts), the MCP exposes product-level visibility, the attribute grid AI builds for your catalog, and the product sub-queries engines fan out to. Products are either claimed (`CATALOG`) or AI-detected (`LLM`).

<AccordionGroup>
  <Accordion title="Which of our products win in AI shopping answers?">
    > *"Show our top and bottom products by AI visibility over the last 30 days."*

    Uses `list_products` ordered by `visibility`. Each row carries mentions, wins, average position, and share of voice. Filter by `category_ids` or `source` (`CATALOG` vs `LLM`) to narrow it down.
  </Accordion>

  <Accordion title="Why does a competitor's product beat ours?">
    > *"Compare our running shoe against the top competitors on the attributes AI mentions."*

    Calls `get_shopping_attributes` with `scope=product`. Returns the characteristics, true/false facts, and ordinal dimensions the models associate with each product, side by side with competitors.
  </Accordion>

  <Accordion title="What sub-queries do engines run for our category?">
    > *"List the shopping sub-queries behind our category prompts last week, and the products each returned."*

    Uses `list_shopping_queries`. Pass a returned `chat_id` to [`get_chat`](/mcp/tools#get-chat) to read the full answer that produced them.
  </Accordion>

  <Accordion title="Load a product catalog">
    > *"Add these 40 products under our brand, in a Shoes > Running category."*

    The assistant resolves the `global_brand_id` with `list_global_brands`, builds the tree with `create_categories`, then calls `create_products` with the category attached — after you confirm.
  </Accordion>
</AccordionGroup>

### Edit your project setup

<AccordionGroup>
  <Accordion title="Add a prompt you just thought of">
    > *"Add this prompt to my project: 'best CRM for remote sales teams 2026'. Target US, tag it 'competitive'."*

    The assistant resolves the tag and the project, then confirms with you before calling `create_prompt`.
  </Accordion>

  <Accordion title="Re-organize prompts under a new topic">
    > *"Create a topic called 'Pricing' and move every prompt that mentions 'cost' or 'pricing' into it."*

    The assistant lists matching prompts first, creates the topic, and calls `update_prompt` for each one. Only after you confirm the list.
  </Accordion>

  <Accordion title="Track a new competitor brand">
    > *"Start tracking Acme as a competitor. Their domains are acme.com and getacme.io, and they also go by 'Acme Labs'."*

    The assistant calls `create_brand` with the domains and aliases you provided.
  </Accordion>

  <Accordion title="Clean up stale tags">
    > *"List my tags, tell me which ones are attached to fewer than 3 prompts, and delete those after I confirm."*

    The assistant uses `list_tags` and `list_prompts`, surfaces the low-use tags, and only calls `delete_tag` for the ones you approve.
  </Accordion>

  <Accordion title="Add a batch of prompts in one go">
    > *"Here are 30 prompts from our customer-research doc. Add them to my project under the 'Discovery' topic, all targeting the US."*

    The assistant resolves the topic ID once, then calls `create_prompts` with all 30 entries in a single batch. Duplicates and any IDs that don't resolve come back per-item so nothing silently fails.
  </Accordion>

  <Accordion title="Refine your brand profile so prompt suggestions improve">
    > *"Read my current brand profile, change the industry to 'B2B SaaS', and add 'AI search analytics' to our product list."*

    The assistant calls `get_project_profile`, shows you the current values, merges your changes, and calls `set_project_profile` after you confirm. Saving triggers a refresh of the AI-generated prompt suggestions.
  </Accordion>
</AccordionGroup>

### Workflows validated in the MCP Challenge

<AccordionGroup>
  <Accordion title="Fix outdated information in AI sources">
    > *"After our pricing change last week, find every URL AI models are citing for pricing-related prompts that still mentions the old price. Draft personalized outreach emails to each publication."*

    The MCP pulls `get_url_report` and `get_domain_report` for pricing topics, uses `get_url_content` to inspect which pages still reference the old price, and drafts outreach. Works for any stale information (pricing, product names, feature lists). Add a Gmail or Firecrawl MCP to the session to send the outreach in the same flow.
  </Accordion>

  <Accordion title="Find which of your pages are losing AI citations">
    > *"For our owned domain, show URLs whose retrieval rate dropped most over the last 90 days compared to the prior 90. Rank them by the size of the drop. These are our content-refresh priorities."*

    Pulls `get_url_report` with `date` dimension filtered to your domain, computes rolling-window deltas, and surfaces URLs where AI engines are citing you less over time. Content refresh is a high-leverage GEO action. Phrase the query to explicitly compare time windows. Vague queries like "which content needs a refresh?" tend to return a generic gap analysis instead of a time-decay ranking.
  </Accordion>

  <Accordion title="Find the prompts where a competitor beats you">
    > *"For every prompt we track, compare our visibility to \[Competitor] and rank the prompts where they beat us most."*

    `get_brand_report` dimensioned by `prompt_id` for both brands returns a ranked gap table. Output: the exact queries where the competitor is mentioned and you are not. Use `list_prompts` to resolve `prompt_id` values to the actual prompt text for the final ranking.
  </Accordion>

  <Accordion title="Find the URL hurting your brand">
    > *"Which URLs are AI models citing most when they describe us negatively?"*

    The MCP pulls `get_url_report` for top-retrieved pages, cross-references with per-chat sentiment via `list_chats` + `get_chat`, and surfaces the specific URLs dragging the score down. Often: an old review, a negative forum thread, or a competitor comparison page.
  </Accordion>
</AccordionGroup>

## Tips

To make the experience smoother or complete, take a look at the following tips:

* **Include dates:** Always specify a time range (e.g. "Last 7 days", "Last month").
* **Name brands:** Mention specific competitors by name (e.g. "How do I compare against \[competitor]?").
* **Ask for breakdowns:** *"Break down by model"* or *"split by topic"* gives per-dimension results.
* **Start broad, then drill down:** Start with your overview, then follow up on what stands out.


# Metrics Overview
Source: https://docs.peec.ai/metrics-overview

The key metrics Peec AI tracks and how they help you understand and improve your AI search performance.

## Brand Metrics

Core metrics that measure your brand's performance in AI responses:

* **Visibility:** Percentage of AI responses where your brand appears. Shows how frequently AI platforms mention your brand when answering relevant prompts. A higher visibility percentage means better brand awareness in AI search.
* **Share of Voice:** Percentage of your brand mentions in AI responses compared to all tracked brands mentioned. A high SoV means that you’re more likely to be the main focus of conversation in chats than competitors.
* **Sentiment:** How positively AI platforms describe your brand (0–100 scale). Based on the language (from words like “trusted,” “reliable,” “leading,” etc., to critical language or negative associations) and context used around your brand mentions. Higher scores indicate more positive brand perception in AI responses.
* **Position:** Your brand’s average ranking when it appears in AI responses. It shows where your brand ranks compared to other brands mentioned. Lower numbers are better: **Position 1** means your brand is mentioned first, **Position 5** means fifth, and so on.
* **Change indicators:** Show performance changes compared to the previous time period of the same length. Display as green up arrows for improvement or red down arrows for decline, with the actual change amount, helping you track trends over time.

## Prompt Metrics

**Prompt volume:** Shows search demand for topics related to your prompts relative to your industry. Uses a 1-5 score (very low to very high) based on real-time search trends, AI conversation data, and industry signals.

## Source Metrics

Metrics that analyze which websites AI platforms use as references when answering your prompts:

* **Domains:**
  * **Retrievals:** Total number of times a URL from this domain appeared as a source across all chats.
  * **Retrieved:** Percentage of chats where at least one URL from this domain appeared as a source.
  * **Retrieval rate:** Average number of times a URL from this domain appeared as a source per chat.
  * **Used as a source:** Share of chats that used one of your own pages as a source.
  * **Citation rate:** Average number of times the domain was explicitly referenced in response text when used. Shows how often the domain gets direct attribution versus background influence.
  * **Total citations:** Total number of inline citations of URLs from this domain across the filtered set.
  * **Citations share:** Share of all inline citations attributed to URLs from this domain across the filtered set.
* **URLs:**
  * **Retrievals:** Total number of times this URL appeared as a source across all chats.
  * **Citation rate:** Average number of explicit citations when this URL was used. Shows how often AI platforms directly reference the page versus using it for background context.
  * **Total citations:** Total number of inline citations of this URL across the filtered set.
  * **Citations share:** Share of all inline citations attributed to this URL across the filtered set.

## Brand visibility vs. source visibility

These two metrics measure different parts of your AI visibility, so it’s important to understand how they differ:

* **Brand visibility:** Your brand name is explicitly mentioned in the response.
* **Source visibility:** Your domain or content was used or cited, even if your brand isn't named.

You can be visible as a **source** without being mentioned as a **brand**, and your brand can be mentioned even when your website isn’t used as a source. Peec AI tracks both to help you identify gaps between the two.

For example:

* If your website is frequently cited but your brand is rarely mentioned, AI may find your content useful without strongly associating it with your brand.
* If your brand is frequently mentioned but your website is rarely cited, AI may associate your brand with the topic without relying on your content as a source.


# Position
Source: https://docs.peec.ai/metrics/brand-metrics/position

How your brand ranks in AI responses.

<img alt="Cleaned7" />

**Position** measures your brand’s average ranking in AI responses, for example, whether it’s mentioned first, second, and so on. A higher position means your brand tends to appear earlier in responses, indicating stronger authority and relevance for the topics being discussed.

## How position is measured

When AI models generate responses, they often mention multiple brands. Your Position reflects where your brand typically appears in those mentions: it is the average ranking across all responses where your brand appears.

<Info>
  Position counts every brand detected in a response, not only your tracked competitors, so your rank reflects where your brand sits among all brands mentioned, including untracked ones.
</Info>

## Why position matters

### Brand authority

A stronger position (closer to 1) indicates that AI models consider your brand to be:

* The most authoritative source for the topic.
* The go-to reference in your industry.
* Highly relevant to the user's query.

### Competitive advantage

Better positioning means:

* Your brand gets more visibility in AI responses.
* Users are more likely to see your brand first.
* You have an edge over other brands.

### Topic relevance

Position can vary by topic, showing you:

* Which topics you're most authoritative in.
* Where you need to improve your content strategy.
* Opportunities to strengthen your expertise.

## Related metrics

<CardGroup>
  <Card icon="heart" href="/metrics/brand-metrics/sentiment" title="Sentiment">
    Learn how the tone of your brand mentions affects your overall performance.
  </Card>

  <Card icon="eye" href="/metrics/brand-metrics/visibility" title="Visibility Score">
    Understand how often your brand is mentioned in AI responses.
  </Card>
</CardGroup>


# Sentiment
Source: https://docs.peec.ai/metrics/brand-metrics/sentiment

The tone and sentiment of your brand mentions.

<img alt="Cleaned6" />

**Sentiment** measures the overall tone of AI responses when they mention your brand, on a scale from 0 to 100. It helps you understand how AI models perceive and describe your brand.

<Info>
  Most sentiment scores fall between 65 and 85, with higher scores indicating more positive language and associations.
</Info>

## How sentiment is measured

The sentiment score analyzes the language used when AI models mention your brand, looking for:

* **Positive indicators**: Words like "trusted," "reliable," "innovative," "leading," "expert".
* **Neutral indicators**: Factual language with little emotional tone.
* **Negative indicators**: Critical language, concerns, or negative associations.

The score is calculated based on the overall tone and context of your brand mentions across all AI responses.

## Why sentiment matters

### Brand reputation

Sentiment directly impacts how users perceive your brand:

* Positive sentiment builds trust and credibility.
* Neutral sentiment maintains professional standing.
* Negative sentiment can damage brand reputation.

### Competitive advantage

Better sentiment means:

* Users are more likely to trust your brand.
* AI models recommend your brand more favorably.
* You have a competitive edge in brand perception.

### Strategic insights

Sentiment analysis helps you:

* Identify reputation issues early.
* Understand how your brand is perceived.
* Track improvements in brand perception over time.

## Related metrics

<CardGroup>
  <Card icon="chart-line" href="/metrics/brand-metrics/position" title="Position">
    Learn how your brand's ranking position affects overall performance
  </Card>

  <Card icon="eye" href="/metrics/brand-metrics/visibility" title="Visibility Score">
    Understand how often your brand is mentioned in AI responses
  </Card>
</CardGroup>


# Share of Voice
Source: https://docs.peec.ai/metrics/brand-metrics/share-of-voice

How much of the conversation you own.

<img alt="Cleaned5" />

**Share of Voice** (SoV) measures the percentage of your brand mentions in AI responses compared with all brands mentioned, including yours. It tells you the share of influence you have whenever AI models mention your tracked brands. Higher SoV means you are more influential than other brands when AI chats mention a brand, even if your visibility differs.

## How the share of voice is calculated

Share of Voice is calculated as:

```text theme={null}
SoV = (Number of times your brand was mentioned) /(Total number of brand mentions) × 100
```

This gives you a percentage that shows how often your brand is mentioned compared to competitors.

## How does share of voice differ from visibility

Visibility measures how often a brand is mentioned in AI answers, while SoV tells you how often your brand is mentioned **compared to all of your tracked competitors.**

For example:

* **Visibility**: If your brand is mentioned in 4 of 10 chats, your visibility is 40%.
* **SoV:** If your brand is mentioned 4 times in 10 chats and your competitor is mentioned 12 times, your share of voice is 25% `(4 / (4 + 12) x 100)`.

## Why the share of voice score matters

### Brand recognition

SoV score directly reflects:

* How influential your brand is in your industry.
* Your brand’s presence in AI answers compared to your competitors.
* The strength of your overall market authority.

### Competitive advantage

Higher SoV means:

* You’re more likely to be the main focus of conversation in chats than competitors.
* AI models prioritize mentioning your brand more often than competitors.
* You are seen as having stronger market authority.

### Strategic insights

SoV analysis helps you:

* Understand your brand’s market influence.
* Identify where you are lacking authority as a brand.
* Track improvements in brand authority over time.

## Related metrics

<CardGroup>
  <Card title="Visibility Score" icon="eye" href="https://docs.peec.ai/metrics/brand-metrics/visibility">
    Understand how often your brand is mentioned in AI responses.
  </Card>

  <Card title="Sentiment" icon="heart" href="https://docs.peec.ai/metrics/brand-metrics/sentiment">
    Learn how the tone of your brand mentions affects your overall performance.
  </Card>
</CardGroup>


# Visibility
Source: https://docs.peec.ai/metrics/brand-metrics/visibility

How often your brand is mentioned in AI responses.

<img alt="Cleaned4" />

The **Visibility Score** measures the percentage of AI responses that mention your brand. It shows how often your brand appears when AI models respond to relevant topics. A higher Visibility Score means your brand is mentioned more frequently, increasing its overall presence in AI-generated answers.

<Info>
  Higher visibility means more AI models recognize and mention your brand when relevant topics are discussed, increasing your overall brand presence in AI-generated content.
</Info>

## How the visibility score is calculated

The visibility score is calculated as:

```text theme={null}
Visibility Score = (Number of responses mentioning your brand / Total responses) × 100
```

This gives you a percentage that shows how often your brand appears in AI responses across all your tracked prompts and competitors.

<img alt="Vis" />

<Tip>
  You can switch the granularity between daily, weekly, and monthly, and choose a line or bar chart.  Click on the 3 dots at the top-right and export as a CSV, save as an image, or copy to clipboard.
</Tip>

## Why the visibility score matters

### Brand recognition

The Visibility Score reflects:

* How well-known your brand is in your industry.
* Whether AI models recognize your brand for relevant topics.
* Your overall market presence and authority.

### Competitive positioning

Higher visibility means:

* You're more likely to be mentioned than your competitors.
* Users are more likely to encounter your brand.
* You have a competitive advantage in brand recognition.

### Strategic insights

Visibility analysis helps you:

* Identify topics where you need more presence.
* Understand your brand's market position.
* Track improvements in brand recognition over time.

## Related metrics

<CardGroup>
  <Card icon="donut" href="/metrics/brand-metrics/share-of-voice" title="SoV">
    Understand how influential your brand is across chats compared to the other tracked brands
  </Card>

  <Card icon="chart-line" href="/metrics/brand-metrics/position" title="Position">
    Learn how your brand's ranking position affects overall performance
  </Card>

  <Card icon="heart" href="/metrics/brand-metrics/sentiment" title="Sentiment">
    Understand how the tone of your brand mentions affects your overall performance
  </Card>
</CardGroup>


# Win rate
Source: https://docs.peec.ai/metrics/brand-metrics/win-rate

How often AI names your brand first.

<img alt="Cleaned12" />

**Win rate** measures the share of AI answers where your brand is ranked first, ahead of every other brand the answer names.

## How win rate is calculated

Win rate is calculated as:

```text theme={null}
Win rate = (Chats where your brand is ranked first) / (Total chats) × 100
```

A chat counts as a **win** when your brand is mentioned and ranks in **Position 1**. The total includes all chats within your selected date range and filters, including those where your brand isn’t mentioned.

<Info>
  Rankings include **every brand detected in the response**, not just your tracked competitors. If an untracked brand ranks ahead of yours, the chat will not count as a win.
</Info>

## How win rate differs from visibility and position

* **Visibility:** Measures the percentage of chats that mention your brand. **Win rate** measures the subset where your brand ranks in **Position 1**, so your Win Rate can never be higher than your Visibility.
* **Position:** Measures your average rank across chats where your brand is mentioned. **Win rate** is calculated across all chats, so a chat that doesn’t mention your brand lowers your Win rate but doesn’t affect your Position.

For example, your brand appears in 6 of 10 chats. It's ranked first in 3 of them and second in the other 3:

* **Visibility:** 60%
* **Position:** 1.5
* **Win rate:** 30% `(3 / 10 × 100)`

## Where to find win rate

* **Overview:** Click **Edit**, then turn on **Win rate** under the **Metrics** tab to add it to your Overview. The **Top brands** table shows the Win Rate for your brand and your competitors.
* **Prompts:** Turn on the **Win rate** column in the table settings to see your Win Rate for each prompt over the selected period, along with the change from the previous period. You can also sort your topics by Win rate.
* **Insights:** Win rate appears in the summary at the top of the page. Select **Win rate** in the performance matrix to compare it across any two dimensions.
* **API and MCP:** The brands report returns `win_rate` and `win_count`. To combine rows, divide the sum of `win_count` by the sum of `visibility_total`.

<Tip>
  Compare **Win rate** with **Visibility** for each prompt. If a prompt has high Visibility but a low Win rate, your brand is appearing in the answer, but another brand is ranking ahead of it.
</Tip>

## Related metrics

<CardGroup>
  <Card icon="eye" href="/metrics/brand-metrics/visibility" title="Visibility">
    Understand how often your brand is mentioned in AI responses.
  </Card>

  <Card icon="ranking-star" href="/metrics/brand-metrics/position" title="Position">
    See where your brand typically ranks when it's mentioned.
  </Card>
</CardGroup>


# My website
Source: https://docs.peec.ai/my-website

See how AI interacts with your website, from visiting and citing your pages to driving traffic and conversions.

**My website** brings everything about your domain’s role in AI into one place. It connects **three** key signals: how AI bots request your site, how your pages appear as sources in AI answers, and how much traffic AI platforms send your way. Together, they show the journey from AI discovering your content to someone visiting and converting on your site.<br /><br />The data shown here comes from your existing [Crawl Insights](https://docs.peec.ai/crawl-insights) server logs and Google Analytics [AI Referral](https://docs.peec.ai/ai-referrals) connection. Connect both sources to get the full picture of how AI interacts with your website and the traffic it drives.

<Info>
  **My website** uses data from integrations you connect elsewhere in Peec: a log source in [Crawl insights](https://docs.peec.ai/crawl-insights) for bot activity, and Google Analytics in [AI referrals](https://docs.peec.ai/ai-referrals) for session starts, conversions, and revenue. If only one is connected, metrics from the other will show as zero.

  **Retrievals** and **citation** data come directly from your tracked prompts, so no additional integration is needed.
</Info>

## Overview

The Overview tab gives you a quick snapshot of your website’s AI performance for the selected domain and date range.

A row of headline metrics, each with its change against the previous period:

* **Bot visits:** AI bot requests to your site in the selected period.
* **Session starts:** AI-referred human sessions that started in the selected period.
* **Conversions:** The number of key events fired by AI-referred visits. What counts as a key event depends on your GA4 setup.
* **Revenue:** Total revenue from completed transactions, minus any refunds. A value appears here if your GA4 property includes purchase revenue.
* **Used as source:** The share of tracked chats that retrieved at least one page from your domain.
* **Cited, not mentioned:** The number of answers that cited one of your pages as a source without naming your brand.

## AI and human traffic

A trend chart comparing two lines over time: **AI bot requests** to your site, and the **human sessions** AI sends you. Switch the time resolution between hourly (on short date ranges), daily, weekly, and monthly to spot trends, spikes, or drops. Use it to see whether crawl activity and referral traffic move together.

On the same chart, you can switch between **citation rate** and **source usage** to see how each metric changes over time.

<img alt="Mywebsitesource" />

## Crawl access

A quick summary of how much of your site AI bots are allowed to visit, based on your robots.txt directives, split into:

* **Fully allowed**
* **Partially allowed**
* **Blocked**

This gives you a quick view of whether AI can access and read your content. Go to [Crawlability](https://docs.peec.ai/crawlability) for a more detailed breakdown.

## Why AI requests you

A breakdown of bot visits by **bot type**, showing the intent behind each request and its share of total bot visits.

<Info>
  The **Bot type** indicates the purpose of the request:

  * **Training** bots collect data to build or refine AI models.
  * **Search** bots crawl the web and index pages to surface in AI search results.
  * **User query** bots fetch content on behalf of a user.
  * **Other** covers bots that don't clearly fall into the above.
</Info>

## Request health

The HTTP status codes AI bots encountered when they requested your site. Use it to spot problems quickly, then follow **All status** through to the Crawl insights detail page to dig deeper. See the [status code reference](/crawl-insights#status-codes) for what each code means.

## Pages

The Pages table is the heart of My website. It shows one row per page on your site, joining your Crawl insights data with your AI referrals and source usage by page path. You can search by path, sort by any column, and export the table to CSV.

| Column | What it means |
| :- | :- |
| **Page** | The page path on your site. |
| **Bot visits** | AI bot requests to this page, from your logs. |
| **Retrievals** | Distinct AI answers that pulled this page in as a source. |
| **Citation rate** | Average number of inline citations per chat when this page is retrieved as a source. |
| **Session starts** | AI-referred human sessions that started on this page, based on GA4 `session_start` events. Most entered on the page; the rest resumed there after idling past GA4's session timeout. |
| **Events** | GA4 events fired on this page by visits AI sent you. |
| **Conversions** | Key events your GA4 property counts, fired on this page. This counts events, so one visit can contribute several. |
| **Revenue** | Purchase revenue booked on this page by visits AI sent you. |

<Info>
  The table is a full join of bot, referral, and source data by page path. If a page has data on only one side, for example, bots visit it, but it hasn't received AI referrals yet, the other metrics show as zero.
</Info>

<Info>
  * **Retrievals** and **Citation rate** come from the prompts you track and are not directly influenced by AI bot activity.
  * **Citation rate** is an average count of citations per chat, not a percentage, so it can be greater than 1.
  * The **Revenue** column appears only when your Google Analytics property reports purchase revenue.
</Info>

### FAQs

<AccordionGroup>
  <Accordion title="What do I need to connect?">
    My website combines two external data sources with your prompt data. Connect an edge/CDN log  source or upload an access log file in [Crawl insights](/crawl-insights) for bot activity, and connect Google Analytics in [AI referrals](/ai-referrals) for sessions, conversions, and revenue. With only one connected, the columns from the other source show as zero.
  </Accordion>

  <Accordion title="How is this different from Crawl insights?">
    Crawl insights focuses on AI bot activity from your edge logs, with folder- and URL-level breakdowns. My website joins that bot data with your AI-referred human traffic and your source performance on a single page, so you can connect crawlability to outcomes like sessions, conversions, and revenue.
  </Accordion>

  <Accordion title="Why does a page show bot visits but no sessions, or the reverse?">
    The Pages table joins three independent data sources. A page can be requested by AI bots without having received AI-referred traffic yet, or receive referral traffic on a path that isn't prominent in your crawl logs for that period. Either way, the missing metrics show as zero. It can also mean one of the two integrations isn't connected yet.
  </Accordion>

  <Accordion title="Can I export the data?">
    Yes. Use the export button above the Pages table to download the current view as a CSV.
  </Accordion>
</AccordionGroup>

## Privacy policy

To read our privacy policy, see the [Privacy Policy for Peec AI](https://peec.ai/legal/privacy-policy).


# Organizing your setup
Source: https://docs.peec.ai/organizing-your-setup

Keep your prompts manageable and analysis-ready with smart organization.

<iframe title="YouTube video player" />

[Watch "Organizing your setup" on YouTube](https://youtu.be/_9Z43OpAumM)

As your prompt collection grows, having a clear way to manage prompts at scale becomes increasingly important. Prompts can have three statuses: **active, archived, and deleted**, with each serving a different purpose.

Organizing prompts into groups also makes your data easier to analyze. Instead of reviewing hundreds of individual prompt results, you can compare performance across meaningful categories and identify broader trends.

## Manage your prompts

Batch actions make it easier to manage multiple prompts at once.

You can select multiple prompts in three ways:

* Click the checkbox next to each prompt you want to select.
* Hold **Shift** and click another checkbox to select a range of prompts.
* Select the checkbox in the top row to select all prompts on the page.

<Info>
  Use search to narrow down your prompts before selecting them, making bulk actions easier to manage.
</Info>

Each tab has its own batch actions.

From the **Active** tab:

* **Assign tags:** Add tags to multiple prompts at once.
* **Assign topics:** Move multiple prompts to different topics. Each prompt can only belong to one topic.
* **Archive:** Archive multiple prompts while keeping their existing data.

From the **Archived** tab:

* **Assign tags and topics:** Manage tags and topics the same way as in the Active tab.
* **Activate:** Reactivate archived prompts back to the Active tab.
* **Delete:** Permanently remove prompts and all associated data. Only use this when necessary.

<Info>
  Prompt states:

  * **Active:** Peec AI runs the prompt against AI models once a day and includes it in analytics.
  * **Archived:** Peec AI stops running it but keeps all chat history and sources in analytics.
  * **Deleted:** Peec AI removes everything associated with the prompt and treats it as if it never existed.
</Info>

## Add your tags and topics

Both tags and topics help you organize prompts, but they work differently and serve complementary purposes. Tags let you add multiple labels for analysis, while topics group prompts into folders and improve prompt suggestions based on your chosen topics.

### Understanding tags vs topics

**Tags:** Dimensions you can use to segment your data for granular views of your brand visibility. One prompt can have multiple tags. For example: "email-marketing," "enterprise," "decision-stage," "q4-campaign."

Tags give you flexible categorization for analysis:

* Filter by single tags or combinations (with AND/OR conditions).
* Compare performance across categories.
* Export data by tag groups.
* Handle overlapping attributes (one prompt can be both "enterprise" and "decision-stage").

**Topics:** Each prompt can belong to only one topic. For example: "CRM Software," "Email Marketing Tools," "Project Management."

Create a new topic with the **Add topic** button on the left side of the prompt table. Topics categorize your prompts and give a folder-like structure for navigation. They're useful when tracking hundreds of prompts, giving you a quick view of your brand's visibility for any given topic. When you view your prompts, they're grouped by topic, and each prompt within a topic can have several tags or none. Prompts without a topic show under the **No Topic** folder.

<img alt="Newtopic" />

With topics, you can:

* Track visibility at the topic level.
* Generate new prompt variations based on topics.
* Filter and segment prompts more effectively.

<Info>
  **Tags** vs. **Topics**:

  * **Tags:** Multiple per prompt, flexible filtering (like Gmail labels).
  * **Topics:** One per prompt, visual folders (like file folders).
</Info>

### **Branded and Intent classification tags**

In addition to the tags you create, Peec AI automatically classifies every prompt by **Branding** and **Intent Type**. Both are shown as dedicated columns in the prompts table and are added automatically when a prompt is created, with no setup required.

<Frame>
  <img alt="System Tags" />
</Frame>

**Branding** tells you whether a prompt searches for your brand by name, or is a generic query where your brand may or may not appear:

* **Branded:** The prompt mentions your brand or a competitor directly. (For example, "What is HubSpot?" or "HubSpot pricing.")
* **Non-branded:** The prompt is a generic question with no explicit brand mention. (For example, "best CRM software" or "how to manage customer relationships.")

**Intent Type** shows the purpose behind each prompt:

* **Informational:** The user is looking for information or wants to understand something. For example, “How do noise-cancelling headphones work?” or “What is cloud storage?”
* **Commercial:** The user is exploring or comparing different options. For example, “Best running shoes for beginners” or “Which meal delivery service is best for families?” or "HubSpot vs Salesforce."
* **Transactional:** The user is closer to making a decision or taking action. For example, “Nike Pegasus price” or “Where to buy an air purifier?”

You can filter your entire prompts table by Branding or Intent Type using the filters at the top of the page. Both are single-select, and you can combine them with your own tag and topic filters for more precise views.

<Info>
  **Branded** and **Intent** classifications are separate from the tags you create yourself. They can’t be renamed, but you can reclassify them for each prompt. Every prompt has exactly one value for each classification.

  If a prompt doesn’t show a value in either column, the classification is still being processed and will appear automatically shortly after.
</Info>

<Tip>
  Use these classifications to spot gaps, opportunities, and patterns in your prompts. For example, filter for **non-branded and commercial** prompts to find topics where your brand has an opportunity to improve visibility without relying on direct brand searches.
</Tip>

## Customize your prompts table

In the prompts table, you can choose which metrics to show or hide and rearrange the columns so the ones most relevant to you appear first. To return to your previous view, open the table settings and click **Reset to default view**.

In addition to the standard metrics, you can also add:

* **Shopping:** The percentage of chats that triggered a shopping carousel.
* **Product comparison:** The percentage of chats where AI compared multiple products.
* **Images:** The percentage of chats that included an image.
* **Ads:** The percentage of chats that triggered an ad.
* **Map:** The percentage of chats that displayed a map in the answer.
* **Web Search:** The percentage of chats that triggered a web search.

<Info>
  These metrics are separate from your main metrics (**Visibility, SoV, Position, and Sentiment**) and do not depend on your brand being mentioned in the chat.
</Info>


# Shopping overview
Source: https://docs.peec.ai/overview

Track how your products appear across AI models by product, competitor, and week.

<iframe title="YouTube video player" />

[Watch "🛒 AI Shopping Analytics: Track How ChatGPT Recommends Your Products | Peec AI" on YouTube](https://youtu.be/yhWL-GoqxKs)

Head to **Shopping** in the sidebar and upload your products to get started. Once your catalog is live, the **Products** table gives you a complete view of how your products perform across AI recommendations.

When someone asks an AI model for a product recommendation, it may return a shortlist of products. **AI Shopping** shows you whether your products make that shortlist, where they rank, and which competitors appear alongside them, helping you understand where your products are performing well and where there’s room to improve.

Unlike brand-level tracking, AI Shopping works at the **product level**. Peec AI matches the products in your catalog with your tracked conversations, giving you visibility, ranking, and competitor insights for individual products, updated daily.

## What AI Shopping tracks

AI Shopping uses the same chat data Peec AI already collects and aggregates it at the product level. Today, this is based on **ChatGPT**, where the product carousel and shopping experience are most advanced. Other AI models may follow as their shopping capabilities evolve.

The focus is on **brands and their products**. Bring your catalog, and Peec AI shows how your products appear in AI answers and how they perform against competitors.

## Overview dashboard

<img alt="Image" />

The Overview brings together signals from each product and shows the bigger picture at the brand level. It helps answer one of the first questions most teams ask: "In my category, which brands show up most often in AI shopping answers, and where does my brand rank?"

Here you'll see:

* **Overview graph (Brands / Products):** The visibility, position, Share of Voice (SoV), and win rate of your brand and competitors over time. Toggle between "Brands" and "Products" on the right to view each. (For products, SoV isn't available.)
* **Top 7 Brands / Products:** Quick overview of the top 7 brands (or products) that are ranking in AI shopping.
* **Performance by visibility:** The products that appear most in AI answers versus the least.
* **Shopping queries:** Aggregated across the prompts you're viewing, these are the queries driving shopping answers. Peec AI surfaces the top queries, the ones gaining the most traction, and the new ones that have started appearing.
* **Shopping fanout queries:** The regular web searches the AI runs while writing its answers. Fanouts shape the text around the carousel, and shopping queries decide which products fill it.

<Info>
  **Shopping queries** overlap heavily with Google Shopping search, so they double as a feed for your wider search and merchandising work.
</Info>

## Best practices

* **Start before you upload a catalog:** Open AI Shopping and review the products Peec AI already detects in your tracked chats. Exploring that view first shows you what the data covers, so you can connect a feed with a clear idea of what you'll get in return.
* **Live in the Products table once your catalog is in.** It brings every metric for every product into one place, and you can filter by category, topic, and tag to focus on the segment that matters most, such as a single product line or campaign.
* **Read win rate alongside visibility, not in isolation.** Visibility shows you how often a product appears; the competitive view shows you what happens when it does. Looking at both together is what separates “we appear often” from “we actually win the slot.”
* **Use Product Detail to find the prompts you lose.** The per-product view shows the exact prompts a product wins and loses, along with the competitors it is measured against. Those losing prompts are your clearest, most specific opportunities for improvement.


# Products
Source: https://docs.peec.ai/products

See every product in your catalog with AI Shopping metrics and detailed insights into visibility, competitors, and attributes.

<img alt="Product" />

Here you can see detailed product-level insights: how products perform, how they're grouped within the categories you've set up, and your full uploaded catalog.

## Product table

<img alt="Image" />

The Products table is where the underlying signal appears. Each row is a product in your catalog, with the metrics Peec AI aggregates from the chats it tracks. Start here to understand what AI Shopping measures.

The table shows these metrics:

| **Metric** | **What it means** |
| :- | :- |
| **Visibility** | The share of chats in which the product gets mentioned. |
| **Win rate** | The share of chats in which the product is the number one recommendation. |
| **Position** | The product’s rank when it appears. Lower is better. |
| **Appearances** | The absolute number of chats the product appeared in. |
| **Catalog price** | The price from your uploaded catalog. |
| **Mentioned price** | The price the AI cites for the product. Compare it to the catalog price to see whether assistants are quoting you higher, lower, or accurately. |
| **Competing brands / products** | The brands and products that show up next to yours in the same chat. |
| **Top shopping queries** | The Google Shopping searches ChatGPT runs to build the product carousel. Optimizing your feed against them is the most direct lever on carousel visibility. |
| **Top fanout queries** | The regular web searches the AI runs to write its answer, where this product surfaced. A different bucket from shopping queries. See [**Understanding chats**](https://docs.peec.ai/understanding-chats) for how fan-outs work. |
| **Attributes** | The attributes ChatGPT uses to compare products in its answer, aggregated by how often each one appears. |

<Info>
  Position is the metric to watch. In a chat, users usually see the first two or three results before they have to scroll, and on mobile that scroll is horizontal. A product that appears often but sits in position eight is barely seen.
</Info>

### Attributes

When ChatGPT compares products, it builds a table of attributes based on the user's question and the context available to it. Peec AI captures those attributes and tracks how often each appears across your chats.

Use this to:

* **Optimize your product detail pages:** If the AI consistently evaluates products on attributes you don't mention on your own pages, it has less to work with when deciding whether to recommend you.
* **Cover the attributes that matter:** Covering the attributes that matter most makes it easier for the model to choose your product. For the full breakdown, see how each attribute scores against competitors in the detail view.

## Product detail page

<img alt="Image" />

The product detail view is where AI Shopping becomes most actionable. Open it by clicking any product in the table. It narrows every metric to a single product for the time range you select, giving deeper insight into that product over time.

### Main KPIs

A summary of the selected product performance over your chosen time period:

* **Visibility:** Percentage of AI responses where this product appears.
* **Win rate:** The share of chats in which the product is the number one recommendation.
* **Position:** Average ranking when this product appears in AI responses (lower is better).
* **Appearances:** The absolute number of chats the product appeared in.
* **Rating:** Average star rating (0–5) across AI answers that rate this product.
* **Mentioned price:** The price the AI cites for the product. Compare it to the catalog price to see whether assistants are quoting you higher, lower, or accurately.
* **Catalog price:** The price from your uploaded catalog.

Change indicators show how each metric moved compared with the previous period of the same length.

<Info>
  Use the filters at the top to analyze more granularly.
</Info>

As you scroll, you'll find graphs, each telling a different story:

* **Visibility & win rate:** Share of AI answers mentioning this product, and how often it is the #1 recommendation, over time.

* **Competing products:** The products ChatGPT recommends alongside this product in the same answer. This shows your competitive set at the product level, helping you understand which specific products are being compared with or recommended alongside yours, rather than only looking at competition at the brand level.

* **Position versus competitors:** A box plot showing where this product typically ranks compared with the products it competes against, sorted by visibility. Beyond the median position, it also shows how much rankings vary and highlights any outliers, giving you a fuller picture of how consistently each product ranks.

* **Merchants:** Where AI is sending shoppers for this product.

* **Sources:** The websites AI retrieved while answering about this product.

* **Shopping queries:** The total number of shopping searches for the selected timeframe. (Product carousels are built from Google Shopping category searches rather than web searches, which makes these queries the most important factor in improving your product's carousel visibility.)

* **Fanout queries:** The web searches triggered alongside those chats, which the assistant uses to generate recommendations, reasoning, and comparisons. (Unlike shopping queries, which determine which products appear in the carousel, fanout queries influence the content and context surrounding them.)

* **Prompts & chats:** The exact prompts and chats this product shows up in, and where it wins or loses.

<Info>
  A product that doesn’t appear often but ranks well when it does looks very different from one that appears constantly in a weak position, and that difference is what tells you where to focus.
</Info>

### Attributes

When the AI compares products, it evaluates them on attributes. The **Products table** shows which attributes come up and how often; this section shows how your product scores on each one against its competitors.

Attributes are split into three tabs by how the AI measures them:

* **Characteristics:** These are attributes with text values. Expand one to see how often the AI mentions each value for you versus your competitors.
* **Facts:** These are yes/no and numeric specs that the AI states about each product.
* **Ratings:** These are attributes the AI scores on a scale, averaged per brand.

The competitor columns are fixed per product, ranked by how much each brand overlaps with the attributes the AI evaluates yours on. An empty cell in your column where competitors have values is a signal: the AI couldn’t find that information about your product. Cover it on your product pages, and you give the model more to work with.

### Prompts & chat table

* **Prompts:** The exact prompts this product appears in, along with visibility, position, and win rate for each. This gives you the clearest view of where you’re winning and where you’re losing. Sort by the metric that matters most to find the prompts worth optimizing.
* **Chats:** The actual AI conversations where this product appeared. Open any chat to read the full answer — what was asked, how the product was presented, and what else was recommended alongside it. If a metric surprises you, this is where you’ll find out why.


# Brand profile
Source: https://docs.peec.ai/project-profile

Your Brand Profile gives Peec the context it needs to tailor topics, prompts, and brand suggestions to your business.

<img alt="Braaandprofile" />

When you connect a domain, Peec AI automatically collects key details about your business, including your company name, what you offer, and who your target customers are. This information forms your **Brand Profile**, which Peec uses to provide suggestions that are more relevant to your business.

The Brand Profile surfaces in two places:

* **During onboarding:** After connecting your domain, a dedicated "Your brand profile" step appears before you reach Topics. This is your first chance to review what Peec AI extracted and make sure it's right.
* **Under project settings:** Once you’re up and running, you can return to your **Brand Profile** at any time by going to **Settings → Profile** under **Project settings**. Any changes you save will refresh your topic and prompt suggestions to reflect the updated information.

Your brand profile includes the following sections:

* **Company name:** The name Peec AI uses to identify your brand across all features.

* **Description:** A short description of what your brand does. Peec uses it in every prompt it generates, so make it specific.

* **Industry:** The specific area your brand operates in.

* **Brand identity:** Adjectives that define your brand.

* **Products and services:** The specific offerings you want tracked and surfaced in AI answers.

* **Personas:** Who your brand is for.

* **Target market:** Where your brand operates. Choose from the drop-down list.

* **Audience distribution:** Define your audience across user types.

## Why it matters

A complete Brand Profile produces better, more relevant prompt recommendations, tailored to your audience, industry, and offerings, so it's easier to see which prompts are worth tracking.

After updating your Brand Profile, go to **All prompts** in your sidebar and open your suggested prompts tab. Click **Suggest more** to generate new suggestions based on your updated profile, then review them and select the most relevant ones to track.

<img alt="Suggestprompts" />

By making the profile visible and editable, Peec AI gives you direct control over the inputs that shape your entire experience.

<Info>
  * Accurate profile = better topics = more relevant prompts = more actionable insights.
  * Your **Brand Profile** also forms the foundation for **Brand Perception** and **Prompt Discovery**, helping Peec tailor these insights and suggestions to your business.
</Info>


# Quickstart Guide
Source: https://docs.peec.ai/quickstart-guide

The fastest way to understand your brand’s AI search presence.

<iframe title="YouTube video player" />

[Watch the full "Getting Started with Peec AI" playlist on Youtube](https://www.youtube.com/playlist?list=PLO3bGBxSo_vU)

This quickstart guide gets you set up fast, so you can dive deeper into the platform with a solid data foundation. It takes less than 10 minutes, and you'll have your first AI visibility insights within 24 hours.

## Step 1: Setting up your prompts

<iframe title="YouTube video player" />

Prompts are the questions you want to be found for in AI search. Peec AI runs them daily across AI platforms like ChatGPT and AI Overviews to see who gets mentioned.

**Your task:** Add your first 10 prompts.

Peec AI suggests prompts based on your brand and website (check the **Suggested** tab on the **Prompts** page, and use **Topics** to get better suggestions), or add your own with the **Add** button.

<Tip>
  If you are unsure where to start, you can ask yourself “What do I want my brand to be found for?” Then take your Google Search Console keywords and rephrase them to be conversational.
</Tip>

**Examples:**

* "What's the best project management tool for creative agencies?"
* "Which CRM is best for marketing agencies under 50 people?"
* "How do I improve email open rates for B2B clients?"

They do not need to be perfect; you can change them later.

## Step 2: Identifying your competitors

<img alt="Socials" />

While your prompts run, Peec AI detects competitor brands mentioned in AI responses and suggests them for you. You can also add social channels that belong to your brand or your defined competitors, making it easier to identify and filter their content in the **Sources** section.

**Your task:** Add 3 to 4 competitors and your social channels.

Go to **Brands** under **Project settings** and:

* Accept suggested competitors that Peec AI detects from your prompt responses, or use **+ Add brand** to add your own.
* Select from the available social platforms and add the relevant handle, channel, or subreddit for your brand. You can also add channels for your defined competitors.

This helps you see which brands appear alongside or instead of yours in AI responses, compare how often they are mentioned, and track the social sources connected to your brand and competitors.

<Info>
  **Important:** Use the shortest unique brand name like "HubSpot" not "[hubspot.com](http://hubspot.com)" or "HubSpot UK", that's exactly what we'll track.

  If there are alternative spellings of a brand name, set them up as aliases.

  For complex cases requiring advanced pattern matching (dictionary words, case sensitivity, context requirements), see our [Advanced RegEx section](https://docs.peec.ai/identifying-your-competitors#advanced-regex).
</Info>

## Step 3: Understanding your dashboard

<iframe title="YouTube video player" />

### Main dashboard view

Your **Overview** gives you a clear view of your brand’s performance first, then helps you explore the insights behind it and identify where to take action. You can also add, remove, resize, and rearrange elements to build a layout that works for you.

Here you can see:

* **Visibility:** How often you appear in the AI answers generated for your prompt set.

* **Share of Voice (SoV):**  Measures the percentage of your brand mentions in AI responses compared with all brands mentioned, including yours.

* **Sentiment:** How positively AI describes you, on a 0 to 100 scale.

* **Position:** Your average rank when you do appear within the response. The lower the number, the better.

* **Used as source:** How often your own domains are used as a source in AI answers.

* **Own source impact:** Track how your visibility changes over time alongside how often your domains are cited as sources in AI responses.

* **Top recommended actions:** Prioritized opportunities to improve your visibility in AI search and improve your brand's performance across the AI models.

* **Performance matrix:** Compare metrics across different dimensions.

* **Source distribution:** The types of sources AI is retrieving to generate its answers.

* **Recent chats:** Latest AI responses generated for your set of tracked prompts.

<Tip>
  Use the filters at the top of your dashboard to filter by AI models, topics, tags, date range, or specific competitors to focus your analysis.
</Tip>

**Customize your dashboard**

<img alt="Editview" />

You're not limited to the elements already shown on the Overview page. Choose from charts across **Brand Insights**, **Brand Perception**, **Attributes**, **Domains**, **URLs**, **Keywords**, **Query Fanouts**, and **Shopping & Products** to build your ideal dashboard.

Here you can:

* **Add element:** Add an element to an existing section. Use **Add element** to create a new section.
* **Rearrange and resize:** Drag widgets to reorder them, or drag their edges to resize. A width of **6 columns** takes up half a row, while **12 columns** span the full row.
* **Delete element:** Click on the "x" at the top-right corner to delete an element.

<Info>
  **Your layout is personal.** Changes are saved to your own account for this project, so rearranging the Overview won't affect your colleagues' layouts.
</Info>

**Share your dashboard**

**Sharing** lets you generate a public, read-only version of your dashboard that anyone can access without a Peec account. Turn it on, then click **Copy public link** to share it. Anyone with the link can view the same elements and data as you, but they can't edit the layout or interact with the dashboard.

* **Password protection:** Add a password to restrict access to the public link.
* **Export as PDF:** Download the current dashboard as a PDF to share in reports or presentations.

<Info>
  A shared link always displays the latest dashboard data. If you need a fixed version that won't change over time, export the dashboard as a **PDF** instead.

  Turning **Sharing** off permanently disables the current link. If you enable sharing again later, a new public link will be generated.
</Info>

**Create custom views**

<img alt="Cusstomviews" />

**Views** let you save multiple versions of your Overview, each tailored to a different purpose. You might create one for your weekly check-in, another for client reporting, and another for tracking competitors.

Each view has a **title** and can include a description. Your default Overview remains unnamed, making it easy to distinguish from the custom views you create.

* **Create a view:** Choose how you want to get started:
  * **Build from scratch:** Open the builder and choose the metrics and elements you want to include.
  * **Start with agent:** Describe what you want to monitor, and the Agent will create a starting layout for you.
* **Find your views:** All the views available to you are collected in the views list, making it easy to return to them whenever you need. Use the **All** and **Bookmarked** tabs to browse your views, or search for a specific one. You’ll also see views your colleagues have shared with you, along with the name of the owner, so you can easily find and reuse layouts your team has already created.

<Info>
  Both options create the same customizable view, with full control over layout, resizing, and sharing. Unfinished views are saved as drafts, which you can resume or discard later.
</Info>

<Tip>
  Bookmark the views you use most often to access them directly from the sidebar without opening the full views list. Bookmarks are personal, so each user can create their own shortlist without affecting anyone else. Your default **Overview** can’t be bookmarked because it’s already the page you land on.
</Tip>

## Step 4: Understanding your sources

<iframe title="YouTube video player" />

When AI platforms search the web for answers, Peec AI captures those sources. They are your biggest opportunity for improvement.

**Your task:** Check the **Sources** page to see which domains and URLs appear most frequently.

You can switch between **Domains** view (like [nytimes.com](http://nytimes.com)) and **URLs** view (specific web pages).

As you review the domains, look for opportunities such as:

* Competitor sites appearing frequently → consider similar content topics.
* Industry publications you're not in → reach out for coverage or guest posts.
* Your own URLs appearing → double down on that content format.
* High "Used" percentage domains → these are authoritative sources worth targeting.

<Tip>
  Let your prompts run for a couple of days before diving deep into analysis. Once you have enough data, focus on the sources appearing most consistently; these are your best targets for content strategy and partnership opportunities.<br /><br />Turn on the **Gap analysis** toggle to show only the sources (domains and URLs) where your competitors are mentioned but your brand is not. This helps you find visibility gaps and top sources where you are invisible.
</Tip>

## What’s next?

Once you are familiar with the basics, you can move on to:

* **Learn the strategy:** Navigate to our [section "How to use source insights"](https://docs.peec.ai/understanding-sources#how-to-use-source-insights) to find out how to work with your source data for maximum impact.
* **Perfect your prompts:** Dive deeper into the [Prompts section](https://docs.peec.ai/setting-up-your-prompts) for advanced setup tips and strategic approaches to get even more valuable insights from your tracking.


# AI bot types — training, indexing, and retrieval bots do different jobs
Source: https://docs.peec.ai/research/ai-bot-types

Peec's server-log guide (Jun 2026) — GPTBot trains models, OAI-SearchBot indexes for AI search, ChatGPT-User fetches pages live per user request; blocking the wrong one solves the wrong problem.

AI bots are three different species, and each maps to a different stage of AI visibility. Peec's server-log guide ([full guide](https://peec.ai/blog/why-server-logs-are-crucial-for-ai-search-strategy), Jun 2026) distinguishes:

* **Training bots (e.g. GPTBot, Common Crawl)** crawl to collect model training data — they shape what the model knows by default. Common Crawl alone holds 300+ billion pages since 2008, and over 80% of GPT-3's training data came from a filtered version of it; it tags pages with PageRank-style importance scores. Blocked training bots mean absence from the model's baseline knowledge, and gaps cannot be fixed retroactively — training data only refreshes at retraining.
* **Search/indexing bots (e.g. OAI-SearchBot)** index content so it can be retrieved and cited in AI search. Blocked indexing bots mean your content never enters the retrieval pool, regardless of quality.
* **User-query/retrieval bots (e.g. ChatGPT-User)** fetch a specific page in real time because a user asked — request-driven, the highest-intent signal of the three.

Unblocking one does not unblock the others: `OAI-SearchBot` (search) and `GPTBot` (training) are separate user-agents with separate robots.txt rules — Deep Research obeys OAI-SearchBot specifically (see [How Deep Research reads your site](/research/how-deep-research-reads-your-site)). The healthiest log pattern is all three bot types present. How to act on the log data: [Server logs for AI search](/research/server-logs-for-ai-search).

**Source:** [Why server logs are crucial for AI search strategy](https://peec.ai/blog/why-server-logs-are-crucial-for-ai-search-strategy), Peec (Tomek Rudzki), Jun 2026.


# The real risk of low-quality AI-generated content
Source: https://docs.peec.ai/research/ai-generated-content-risk

Peec's analysis (Feb 2026) — sites publishing raw AI content at scale suffer Google visibility drops, including 36–75% of AI-content tools' own success stories.

Publishing raw AI-generated content at scale can tank online visibility. Peec's analysis ([full article](https://peec.ai/blog/the-real-risk-of-ai-generated-content), Feb 2026) documents the pattern: sites with poor-quality AI content rank for a while, then drop — sometimes dramatically.

* **The vendors' own customers show it.** 36% of brands in one popular AI-content tool's success-story section show the "Mount AI" traffic pattern in Google (sharp rise then massive drop); at another platform it was 3 of 4 featured brands (75%).
* **Grokipedia is the marquee case:** it lost Google visibility in late January/early February 2026, and answer engines (ChatGPT, AI Mode, AI Overviews) reduced Grokipedia citations at exactly the same time — see [Google rankings affect AI visibility](/research/google-rankings-affect-ai-visibility).
* **Google can detect low-effort AI content.** Google's own 2020–2021 research tested AI detectors on 500 million pages; a researcher from that study now works on AI-content detection at DeepMind. Google's 2025 Quality Rater Guidelines explicitly mark mass-produced, no-original-value pages "Lowest" quality, and Originality.AI found 100% of sites removed in Google's 2024 spam update carried AI-generated posts.
* **User signals compound it:** bounces from slop pages feed back into rankings (confirmed for Bing, and for Google via patents and antitrust revelations).

The safe use (per Lily Ray, quoted in the piece, Feb 2026): AI as writing assistant — ideation, outlining, editing — with unique insights, firsthand expertise, or original research added; never raw output published at scale.

**Source:** [The real risk of AI-generated content](https://peec.ai/blog/the-real-risk-of-ai-generated-content), Peec (Tomek Rudzki), Feb 2026.


# AI Overviews by country — 76% in the EU, 90% outside, 0% in France
Source: https://docs.peec.ai/research/ai-overviews-by-country

Peec's 500,000-prompt study (Apr 2026) — AI Overviews shows in 76% of EU searches vs 90.3% outside the EU; US 91.4%, UK 91.7%, Germany 75.6%, and France 0% (no AI Overviews or AI Mode).

Google AI Overviews appears less often inside the European Union than outside it. In Peec's 500,000-prompt study (April 13–20, 2026, [full study](https://peec.ai/blog/ai-overviews-is-the-most-undertracked-ai-search-500-000-prompts-show-why)), AI Overviews showed in **76% of EU searches** versus **90.3% outside the EU**.

Breakdown across major markets (April 2026):

* **US:** 91.4%
* **UK:** 91.7%
* **Australia:** 86.5%
* **Poland:** 82.9%
* **Germany:** 75.6%
* **France:** 0% — the only major market where neither AI Overviews nor AI Mode is served.

Keep the gap in proportion: at 76%, AI Overviews still appears in more than three of every four EU searches, so the study's conclusion is that AI Overviews has reached maturity in almost every market (76–91%) and deserves tracking everywhere except France. Overall appearance rates and growth are in [How often AI Overviews appears](/research/ai-overviews-how-often-it-appears).

**Source:** [AI Overviews is the most undertracked AI search: 500,000 prompts show why](https://peec.ai/blog/ai-overviews-is-the-most-undertracked-ai-search-500-000-prompts-show-why), Peec (Tomek Rudzki), May 2026.


# AI Overviews by query intent — commercial queries trigger it too
Source: https://docs.peec.ai/research/ai-overviews-by-query-intent

Peec's 500,000-prompt study (Apr 2026) — AI Overviews appeared for 88.5% of bottom-of-funnel commercial prompts, above the 87% average, and in 93–97% of queries with a clear intent pattern.

Google AI Overviews is not reserved for informational queries — it appears across the whole funnel. Peec classified 500,000 prompts (April 13–20, 2026) by funnel stage ([full study](https://peec.ai/blog/ai-overviews-is-the-most-undertracked-ai-search-500-000-prompts-show-why)) and found decision-stage, bottom-of-funnel prompts trigger AI Overviews **88.5%** of the time — higher than the 87% average. Queries like "best CRM for small business" or "Salesforce vs HubSpot" get AI Overview answers that recommend some brands and leave others out.

By query type (Google's eight internal categories, per Mark Williams-Cook's research): **AI Overviews appears in 93–97%** of queries with a clear linguistic intent pattern — short fact, yes/no, instruction, definition, reason, comparison, and consequence — with the exact category barely changing the rate. The one outlier is the vague "Other" bucket at **67%**. When Google can read a clear intent, it almost always serves an AI Overview.

Related pages: [How often AI Overviews appears](/research/ai-overviews-how-often-it-appears), [AI Overviews by query length](/research/ai-overviews-by-query-length), [AI Overviews by country](/research/ai-overviews-by-country).

**Source:** [AI Overviews is the most undertracked AI search: 500,000 prompts show why](https://peec.ai/blog/ai-overviews-is-the-most-undertracked-ai-search-500-000-prompts-show-why), Peec (Tomek Rudzki), May 2026.


# AI Overviews by query length — longer queries trigger it more
Source: https://docs.peec.ai/research/ai-overviews-by-query-length

Peec's 500,000-prompt study (Apr 2026) — two-word queries get an AI Overview 64.6% of the time, rising with every word to a 89.1% peak at 11–15 words: a 25-percentage-point swing.

Query length strongly predicts whether Google serves an AI Overview. Splitting 500,000 prompts by word count (April 13–20, 2026, [full study](https://peec.ai/blog/ai-overviews-is-the-most-undertracked-ai-search-500-000-prompts-show-why)), Peec found the rate climbs with nearly every added word:

* **2 words** ("car insurance"): 64.6%
* **5 words:** 78.5%
* **6–7 words:** 84.2%
* **8–10 words:** 87.7%
* **11–15 words:** 89.1% (peak)
* **15+ words:** plateau between 87% and 91%

That is a 25-percentage-point swing between the shortest and longest queries. One-word queries are an oddity at almost 80% — even "marketing" got an AI Overview. Average across all lengths: 87% (April 2026 data).

Even keyword-style two-word queries see AI Overviews in nearly two of three searches, so short queries do not escape it. Overall coverage and growth are in [How often AI Overviews appears](/research/ai-overviews-how-often-it-appears); intent-level rates in [AI Overviews by query intent](/research/ai-overviews-by-query-intent).

**Source:** [AI Overviews is the most undertracked AI search: 500,000 prompts show why](https://peec.ai/blog/ai-overviews-is-the-most-undertracked-ai-search-500-000-prompts-show-why), Peec (Tomek Rudzki), May 2026.


# How often Google AI Overviews appears — 87% of searches
Source: https://docs.peec.ai/research/ai-overviews-how-often-it-appears

Peec's 500,000-prompt study (Apr 2026) — AI Overviews appeared in 86.7% of Google searches, up from 56.9% in Apr 2025, and reaches 2.5 billion monthly users, the largest AI search surface.

Google AI Overviews appears in roughly 87% of Google searches, based on Peec's analysis of 500,000 prompts from April 13–20, 2026 ([full study](https://peec.ai/blog/ai-overviews-is-the-most-undertracked-ai-search-500-000-prompts-show-why)). Coverage grew from **56.9%** of searches in April 2025 to **86.7%** in April 2026 — a 50% increase in twelve months.

Scale context from the same study: Google confirmed at I/O 2026 that AI Overviews reaches **2.5 billion monthly users** — larger than ChatGPT, Claude, and Perplexity combined — with AI Mode at 1 billion and Gemini at 0.9 billion, all on the same Google AI stack.

Methodology note: the dataset skews toward business-oriented prompts with buying intent (category research, comparisons, decision-stage evaluations) and excludes navigational queries like "HubSpot" or "Tesla."

Appearance varies by dimension, each with its own page:

* [AI Overviews by query intent](/research/ai-overviews-by-query-intent) — 88.5% on bottom-of-funnel prompts; 93–97% on clear-intent query types.
* [AI Overviews by country](/research/ai-overviews-by-country) — 76% inside the EU vs 90.3% outside; France 0%.
* [AI Overviews by query length](/research/ai-overviews-by-query-length) — 64.6% for two-word queries up to 89.1% at 11–15 words.

**Source:** [AI Overviews is the most undertracked AI search: 500,000 prompts show why](https://peec.ai/blog/ai-overviews-is-the-most-undertracked-ai-search-500-000-prompts-show-why), Peec (Tomek Rudzki), May 2026.


# AI agents read your image alt text as content
Source: https://docs.peec.ai/research/ai-reads-image-alt-text

Peec's Deep Research logs (Jun 2026) — ChatGPT's agent reads image alt text as page content, lifting ratings straight from alt attributes; images without alt text are skipped as decorative.

Image alt text is the only thing ChatGPT's Deep Research agent can read from an image — and it treats it as page content. Peec's recorded session logs ([full study](https://peec.ai/blog/how-chatgpt-deep-research-reads-your-site-what-the-logs-reveal), Jun 2026) show every image rendered into the read text as a marker carrying its alt attribute.

Two documented behaviors (Jun 2026):

* **Alt text becomes facts in answers.** On a comparison task the agent lifted a rating straight from alt text — "The image alt text mentions 'Defaqto 5-star' and 'Which? Recommended Provider…'. I'll note these details and verify their accuracy." A badge, chart, or award graphic with rich alt text can put its claim into the AI answer.
* **No alt text means invisible.** With `alt=""` or a meaningless filename, the agent reads the filename and gives up: "It seems to be a vector graphic ('awardwinning-360x140.svg')… likely just decorative, so I'll skip it."

The action: write real, fact-carrying alt text on every meaningful image — ratings, award names, chart takeaways — because in this pipeline alt text is content, not an accessibility afterthought. How the rest of the page gets read: [How Deep Research reads your site](/research/how-deep-research-reads-your-site).

**Source:** [How ChatGPT Deep Research reads your site: What the logs reveal](https://peec.ai/blog/how-chatgpt-deep-research-reads-your-site-what-the-logs-reveal), Peec (David Konitzny), Jun 2026.


# How to write a paragraph AI will cite — answer shape wins
Source: https://docs.peec.ai/research/answer-shape-for-ai-citations

Peec's reranker tests (Aug 2026) — writing one direct-answer sentence at the top of a paragraph is the highest-leverage edit; an on-topic description scored near zero, a direct answer >99%.

Writing a paragraph so AI search cites it comes down to answer shape: "about the topic" and "answers this query" are different tests. Peec ran 12 open rerankers on the same two passages for the query "what are the best AEO tools" ([full guide](https://peec.ai/blog/rerankers-for-geo-aeo-how-ai-search-chooses-passages-and-sources), Aug 2026): a product description scored near zero on strict models (MiniLM 0.0019%, BGE-large 0.20%), while a direct shortlist — "The best AEO tools in 2026 are…" — scored above 99% on every model. Every model scored the direct-answer version higher.

What follows for content (Aug 2026 findings):

* **The cheapest high-impact edit is one direct-answer sentence** in the first two lines of each query-targeting section — answer first, evidence and nuance after.
* **Match intent to answer shape:** a shortlist with criteria for "best X" queries, a concise definition for "what is X", like-for-like criteria for "X vs Y", ordered steps for "how to", an exact dated value for price/status questions.
* **Missing concepts matter more than word order.** Cover the decision criteria and entities the intent requires (audience, price, year, alternatives) — repetition is not coverage.
* **Make sections locally self-contained:** name the subject explicitly instead of "it/this tool", keep the answer next to its evidence — whatever window a system cuts is judged alone.

A model score is not a citation guarantee — authority, freshness, diversity rules, and the generating LLM all still gate the final answer (see [How AI search chooses passages](/research/how-ai-search-chooses-passages)). Why this mechanic favors listicles: [Why listicles get cited](/research/why-listicles-get-cited). What not to over-do: [The reranker-friendly chunks myth](/research/reranker-friendly-chunks-myth).

**Source:** [Rerankers for GEO/AEO: How AI search chooses passages and sources](https://peec.ai/blog/rerankers-for-geo-aeo-how-ai-search-chooses-passages-and-sources), Peec (Metehan Yesilyurt), Aug 2026.


# AI assistants judge companies by their brand name
Source: https://docs.peec.ai/research/brand-name-bias-in-ai-descriptions

Peec research (Aug 2026) — a brand name one point more positive earns descriptions 0.07 points more positive, and on GPT 5.6 Terra 1 in 12 lab descriptions described the name, not the company.

The words in a company's brand name influence how AI assistants describe the company — strongest when the model knows little about the business. Peec measured this in Aug 2026 ([full study](https://peec.ai/blog/ai-assistants-judge-your-company-by-its-name-i-measured-how-much)) using the Warriner et al. (2013) human-rated word-valence dataset (\~14,000 English words, 1–9 scale).

* **In the wild (904 single-word-name brands, five assistants):** a name one point more positive on the human scale predicts descriptions 0.07 points more positive, surviving controls for sector, model, and founding decade. The median brand scores 6.47/9 — the same as "cucumber" — and the middle 50% of brands span just 0.38 points, roughly "donkey" (6.29) to "dolphin" (6.67), so a name swap covers most of the range.
* **In the lab (80 matched positive/negative fictional name pairs, 4 models, web search off):** the nicer name earns better descriptions on nearly every model, and the effect grows with newer models — GPT 5.6 Terra's effect is roughly 4× Gemma 4's.
* **Semantic takeover:** in rare cases the model describes the dictionary word instead of the company — a fictional payroll company named *Unethical Inc.* came back "Dishonest, Corrupt, Deceptive." On GPT 5.6 Terra this happened in **1 of 12 descriptions**.
* **The catch:** known brands are immune. Discord, Riot, and Slack are described as companies, not words — the effect lives only where the model lacks information, and disappears once a brand is known.

Takeaway (Aug 2026): new brands should mind the dictionary meaning of their name; existing brands fix it by becoming known, not by renaming.

**Source:** [AI assistants judge your company by its name: I measured how much](https://peec.ai/blog/ai-assistants-judge-your-company-by-its-name-i-measured-how-much), Peec (Jan Ehrlinspiel), Aug 2026.


# ChatGPT fan-out targeting — domains persist, URLs churn
Source: https://docs.peec.ai/research/chatgpt-fanout-domains-vs-urls

David Konitzny tracked 500 prompts for 17 days after GPT-5.6 launched (Aug 2026) — 91.9% of site: targets are bare domains, 18.1% of domains recur almost daily, only 3.5% of URLs repeat.

Domain-level visibility is a more stable signal than URL-level visibility in ChatGPT's fan-outs. David Konitzny tracked 500 prompts (no brands or domains mentioned) daily for the 17 days after GPT-5.6's release ([full article](https://www.linkedin.com/pulse/how-unique-domains-urls-chatgpt-query-fan-outs-david-konitzny-aqmze/), Aug 2026), analyzing every `site:` occurrence:

* **91.9% of site: cases target only a domain;** roughly 9% include a full URL path — and those paths point at pricing, feature, or individual product pages.
* **Domains show persistence:** 45% are one-offs, 55% appear multiple times, and **18.1% recur almost every day** — a stable hard core, even as ChatGPT keeps discovering new domains at a slowing rate.
* **URLs churn:** 64.9% are one-offs and only **3.5% repeat across the dataset**; the cumulative distinct-URL curve keeps climbing with no plateau.

Interpretation: ChatGPT converges on a trusted set of domains while continuously exploring different pages within them. For measurement, domain-level visibility is the more meaningful signal; counting raw site:-operator occurrences without separating domain vs URL targeting misreads the behavior. How the operator is used qualitatively: [ChatGPT site-operator fan-outs](/research/chatgpt-site-operator-fanouts).

**Source:** [How unique are domains and URLs in ChatGPT query fan-outs?](https://www.linkedin.com/pulse/how-unique-domains-urls-chatgpt-query-fan-outs-david-konitzny-aqmze/), David Konitzny, LinkedIn, Aug 2026.


# ChatGPT fan-outs doubled in length in four months
Source: https://docs.peec.ai/research/chatgpt-fanout-length-trend

Peec's 20M fan-out analysis — average QFO word count rose from ~6 words in Oct 2025 to ~12 by Jan 2026, uniformly across countries and languages, while fan-outs per prompt stayed constant at 2.3–2.8.

ChatGPT's query fan-outs roughly doubled in length between October 2025 and January 2026. Peec analyzed over 20 million ChatGPT fan-outs across countries ([full study](https://peec.ai/blog/country-analysis-20-million-search-qfos), Feb 2026):

* Average word count rose from **\~6 words (Oct 2025) to \~12 words (Jan 2026)**, with a brief peak of \~16 words around calendar week 49 of 2025.
* The trend is **uniform across countries and languages** — Germany, UK, Singapore, Thailand, US all follow the same curve, confirmed by character counts. ChatGPT's algorithm changes apply globally, unlike Google organic search, which varies by locale.
* **Fan-outs per prompt stayed roughly constant:** 2.4–2.8 per prompt in early October 2025, 2.3–2.8 in late January 2026. ChatGPT makes each query more precise rather than running more queries.

Two likely reasons: longer queries give vector-embedding retrieval and re-ranking richer signals to match against, and more specific queries cut through an internet increasingly saturated with AI-generated content.

Implication for content: broad, generic pages struggle to match increasingly specific fan-outs; detailed content addressing specific intents gains retrieval advantage. Note that GPT-5.6 (Aug 2026) later changed the fan-out count picture substantially — see [GPT-5.6 retrieval changes](/research/gpt-56-retrieval-changes). Definition: [What is a query fan-out](/research/what-is-a-query-fanout).

**Source:** [ChatGPT fan-outs have doubled in length in 4 months](https://peec.ai/blog/country-analysis-20-million-search-qfos), Peec (Tom Wells), Feb 2026.


# ChatGPT vs Google — the real search market share
Source: https://docs.peec.ai/research/chatgpt-google-market-share

Peec's two-method estimate (Oct 2025) puts ChatGPT at 4–12% of Google's search volume — roughly 600 million searches per day — far above the 0.6% suggested by click data alone.

ChatGPT's real search volume is roughly 4–12% of Google's — far more than click data suggests. Peec's analysis ([full study](https://peec.ai/blog/the-real-search-engine-market-share-of-chatgpt), Oct 2025) corrects the widely quoted 0.6% figure from Ahrefs click data, which undercounts ChatGPT because ChatGPT answers directly and rarely needs a click, while Google's blue links demand them.

Two independent methods converge:

* **Usage data:** OpenAI/Harvard research (Sep 2025) reports 2.5 billion ChatGPT prompts per day, 24% classified as information-seeking → \~600 million searches/day, vs Google's \~14 billion → **4.3%**.
* **Referral traffic adjusted for CTR:** Google converts \~40% of searches to external clicks; AI-answer surfaces convert \~5% (iPullrank measured 3.8–5.4% for Google AI Mode; Semrush \~3–7%). Re-basing the Ahrefs click ratio on those CTRs yields **4.6%**, or up to 12% if ChatGPT's CTR is as low as 2%.

Bottom line (Oct 2025 estimates): ChatGPT processes roughly 500 million to 1.7 billion searches per day; Google is 8× to 22× bigger by search volume — but ChatGPT is more than an order of magnitude bigger than click-through data implies. Google's own AI surface is larger still: AI Overviews reaches 2.5 billion monthly users — see [How often AI Overviews appears](/research/ai-overviews-how-often-it-appears).

**Source:** [The real search engine market share of ChatGPT](https://peec.ai/blog/the-real-search-engine-market-share-of-chatgpt), Peec (Malte Landwehr), Oct 2025.


# ChatGPT has its own search index — the Labrador family
Source: https://docs.peec.ai/research/chatgpt-own-search-index-labrador

Peec's investigation (Sep 2026) — ChatGPT runs its own retrieval index, internally called Labrador, a family of vertical indexes for web, PDF, YouTube, news, shopping and more.

ChatGPT runs its own retrieval index, internally called Labrador — not just Bing or Google. Peec's investigation ([full study](https://peec.ai/blog/chatgpt-built-its-own-search-index), Sep 2026) found the evidence directly in ChatGPT's server-side events (SSE): between May 21 and July 21, 2026, a `result_source` field carried exactly four values — Labrador, Bright, Oxylabs, and SERP. Three are external scraping providers; Labrador is OpenAI's own index.

Labrador is not one index but a family of vertical ones: general web, PDF, YouTube, news (with separate tiers for the last day, last 7 days, and older), arXiv, Wikipedia, local, finance (including a separate PDF index), legal, medical, shopping, and images. It stores what Google's index stores — full page content, crawl date, and publication date. This is the same architecture Google spent two decades building: a general web index plus specialized verticals layered on top.

Corroborating evidence from the Sep 2026 investigation:

* **OpenAI job postings.** One asks for "designing and operating indexing systems, retrieval pipelines, and serving layers"; another describes running indexing services behind ChatGPT at **exabyte scale** with vector search. A research role targets dense, sparse, and hybrid retrieval — the setup for the Reciprocal Rank Fusion (RRF) merging that Peec researcher Metehan Yesilyurt [documented first](https://metehan.ai/blog/chatgpt-is-using-reciprocal-rank-fusion-rrf/).
* **Antitrust testimony.** During Google's antitrust trial, Nick Turley (head of ChatGPT) [testified](https://www.justice.gov/atr/media/1402141/dl) that OpenAI had "significant quality issues" with non-Google search API partners, that Google refused to license its index, and that OpenAI began building its own search index in 2023 — targeting 80% of queries from it by end of 2023. He also said that even with full access to Google's data, it would take at least five years to determine whether answering 100% of queries from its own index is achievable.

ChatGPT still is not running on its own pipelines alone — it blends the Labrador index with Google, Microsoft and at least eight outside providers; see [Where ChatGPT search results come from](/research/chatgpt-search-result-providers). The index push is most visible in shopping — see [ChatGPT Shopping runs on OpenAI's own product index](/research/chatgpt-shopping-index-experiments).

**Source:** [ChatGPT built its own search index](https://peec.ai/blog/chatgpt-built-its-own-search-index), Peec (Tomek Rudzki), Sep 2026.


# ChatGPT caches pages instead of fetching them live
Source: https://docs.peec.ai/research/chatgpt-page-caching

Peec's investigation (Sep 2026) — ChatGPT serves pages from its own cache, confirmed via lockdown mode; a 1-billion-page test site was crawled at 35,000 requests per hour.

ChatGPT serves many pages from its own cache rather than fetching them live. Peec's investigation ([full study](https://peec.ai/blog/chatgpt-built-its-own-search-index), Sep 2026) confirmed it via ChatGPT's lockdown mode — a setting that cannot browse live pages but can still return offline or cached results. Asked "show me the latest version of homepage" for major SEO publishers (Search Engine Journal, Search Engine Land, Search Engine Roundtable), lockdown-mode ChatGPT returned the pages anyway — served from cache, not fetched live.

Why a cache has to exist: live retrieval is too slow at ChatGPT's scale. Per the [HTTP Archive Almanac](https://almanac.httparchive.org/en/2024/performance#time-to-first-byte-ttfb), 58% of pages take longer than 0.8 seconds to load. Caching also lets OpenAI front-load the expensive work — computing embeddings in advance and filtering out low-quality pages before they reach the pipeline.

The crawl behavior matches. Peec researcher Metehan Yesilyurt published a test website with one billion pages to measure how much ChatGPT would crawl: by the beginning of September 2026 it had crawled 6 million of those pages and was still going at 35,000 requests per hour. Crawling that aggressively only makes sense if the pages are headed into a cache or an index — see [ChatGPT has its own search index](/research/chatgpt-own-search-index-labrador).

Practical check from the study: enable lockdown mode in ChatGPT settings and ask about your most important pages — it reveals whether ChatGPT has already cached them.

**Source:** [ChatGPT built its own search index](https://peec.ai/blog/chatgpt-built-its-own-search-index), Peec (Tomek Rudzki), Sep 2026.


# Where ChatGPT search results come from — Google, Bing, Web IQ and 8+ providers
Source: https://docs.peec.ai/research/chatgpt-search-result-providers

Peec's investigation (Sep 2026) — on top of its own index, ChatGPT stitches at least eight providers, including Google, Bing, Microsoft's Web IQ, Yelp and TripAdvisor. Bing is not a proxy.

ChatGPT's search results come from its own index plus at least eight external providers — not from Bing alone. Peec's investigation ([full study](https://peec.ai/blog/chatgpt-built-its-own-search-index), Sep 2026) mapped every provider visible in ChatGPT's server-side events and public confirmations:

* **OpenAI's own crawler and Labrador index** — see [ChatGPT has its own search index](/research/chatgpt-own-search-index-labrador).
* **Bright (very likely Bright Data)** — scrapes Google's web results directly, and separately scrapes Google Maps for local listings.
* **Oxylabs** — scrapes Google and feeds the news vertical specifically.
* **A third SERP-scraping channel** — tagged simply "serp", also serving news plus a mixed local-results version.
* **Yelp** and **TripAdvisor** — treated as licensed partners for local data.
* **Two anonymous internal pipes (b1 and b3)** — b1 surfaces business websites and Facebook pages, b3 routes to Google Maps.
* **Web IQ** — Microsoft's grounding platform (sub-165ms P95 latency), which [Microsoft itself confirms](https://www.microsoft.com/en-us/webiq) already powers ChatGPT alongside Copilot and Nasdaq.

Direct evidence that Google and Bing still matter (Sep 2026):

* **Google:** Malte Landwehr (CPO, Peec) picked a website with zero organic traffic and asked only ChatGPT about it on specific days — Google Search Console showed a traffic spike for that exact site on those days. ChatGPT still queries Google while grounding answers. This is also why a Google ranking loss carries into ChatGPT — see [Losing Google rankings kills AI search visibility](/research/google-rankings-affect-ai-visibility).
* **Bing:** shows up mainly in Deep Research — SSE events during Deep Research sessions reference Bing as a result source, as flagged by Peec researcher [David Konitzny](https://www.linkedin.com/posts/davidkonitzny_bing-is-now-officially-a-result-source-in-share-7478896640515354624-ZQRk/).

Strategy consequences the study draws: stop assuming Bing visibility is a proxy for ChatGPT visibility — what looks like Bing may be routed through Microsoft's Web IQ, a different product. If local listings matter, get Yelp and TripAdvisor right first; Google Maps data reaches ChatGPT anyway, but without you controlling how it is sourced.

**Source:** [ChatGPT built its own search index](https://peec.ai/blog/chatgpt-built-its-own-search-index), Peec (Tomek Rudzki), Sep 2026.


# ChatGPT searches in English even when users don't
Source: https://docs.peec.ai/research/chatgpt-searches-in-english

Peec analysed 10M+ prompts and 20M fan-outs (Feb 2026) — 78% of non-English ChatGPT sessions include English sub-searches, and 43% of all fan-outs for non-English prompts run in English.

ChatGPT conducts much of its background research in English regardless of the user's language. Peec analyzed over 10 million prompts and 20 million query fan-outs, filtered to cases where user location matched query language — Polish queries from Poland, German from Germany, Spanish from Spain ([full study](https://peec.ai/blog/chatgpt-searches-in-english-even-when-you-don-t), Feb 2026).

* **In nearly 78% of non-English cases**, ChatGPT supplements the query with additional English-language research; across all non-English sessions analyzed, at least one sub-search hits the English web.
* **43% of all fan-out research steps** for non-English prompts run in English.
* By language: Turkish switches most at 94%, Spanish least at 66% — no non-English language falls below 60% (Feb 2026 data).

The consequence: local market leaders lose to global brands in their home market. Documented examples include German software queries returning zero German companies, and Allegro.pl (Poland's dominant marketplace) missing from Polish auction-portal answers while eBay ranks. ChatGPT even rewrote a Spanish cosmetics query into "top *global* cosmetic brands" on its own.

Why: English content carries more authority signals (backlinks, citations), and with \~50% of internet content in English, English queries reduce retrieval risk. What to do: identify which English sources ChatGPT trusts in your category and get present in them — strategic English content beats blind translation. Google's surfaces stay closer to the query language — see [Optimizing for Google AI vs ChatGPT](/research/optimizing-google-ai-vs-chatgpt) and [Translated Reddit citations](/research/reddit-translated-citations).

**Source:** [ChatGPT searches in English, even when you don't](https://peec.ai/blog/chatgpt-searches-in-english-even-when-you-don-t), Peec (Tomek Rudzki), Feb 2026.


# ChatGPT Shopping runs on OpenAI's own product index — live A/B experiments
Source: https://docs.peec.ai/research/chatgpt-shopping-index-experiments

Peec's investigation (Sep 2026) — five live A/B experiments test OpenAI's own product index in ChatGPT Shopping; ranking blends BM25, a 400-candidate reranker and vector search.

ChatGPT Shopping is where OpenAI's own search index is most visible in production. Peec's investigation ([full study](https://peec.ai/blog/chatgpt-built-its-own-search-index), Sep 2026) spotted an A/B experiment named "prefer-index-over-serp-v3" in ChatGPT's server-side events in mid-August 2026, affecting 8% of chats at the time — OpenAI testing its own product index against scraped search results on traffic slices from single digits up to 20%.

As of September 2, 2026, at least five separate shopping experiments were running: prefer-index-over-serp-v3, chatgpt-shopping-noamazon, shopping-index-q2qb, shopping-hqi-v2, and shopping-hq-v1. Whether "hqi" stands for "high quality index" is not confirmed; what is confirmed is that both prefer-index-over-serp-v3 and shopping-index-q2qb run on ChatGPT's own index — see [ChatGPT has its own search index](/research/chatgpt-own-search-index-labrador).

The ranking stack behind one experiment ("shopping-reduced-topn-v4b"), visible in the same events:

* **BM25 lexical component** — narrows the field to 10 sources for ranking.
* **rerank400** — reranks a pool of 400 candidates.
* **prod400** — 400 products used as the input pool.
* **ann4096** — approximate nearest neighbor (vector search), run at two dimensions: 12,288 and 4,096.

Multiple ranking signals blended, then A/B tested against real traffic until the mix earns its place in production. The study's advice for anyone selling products: watch how you show up in ChatGPT's shopping results specifically — that is where the index push affects product selection today.

**Source:** [ChatGPT built its own search index](https://peec.ai/blog/chatgpt-built-its-own-search-index), Peec (Tomek Rudzki), Sep 2026.


# ChatGPT site-operator fan-outs — 84% branded, Reddit tops the rest
Source: https://docs.peec.ai/research/chatgpt-site-operator-fanouts

David Konitzny's GPT-5.6 analysis (Jul 2026) — the site: operator appears in ~43% of fan-outs (vs 0.004% in GPT-5.5); 84% target brand domains, and Reddit is 71% of non-branded site-operator domains.

ChatGPT 5.6 uses the `site:` operator as a core retrieval tool. David Konitzny's analysis of GPT-5.6 (Luna) fan-outs ([full article](https://www.linkedin.com/pulse/understanding-site-operator-usage-chatgpt-56-fan-outs-david-konitzny-sycce/), Jul 2026) found it in roughly **43% of query fan-outs**, versus 0.004% in ChatGPT 5.5.

How it is used (Jul 2026 data):

* **Mostly one domain per fan-out** — only 9% of cases carry two or three site: commands. The operator narrows the information space to a trusted source.
* **84% of targeted domains are branded** — the model goes straight to the domain offering the relevant product or service. Only 16% are non-branded secondary sources.
* **Reddit is 71% of all non-branded site-operator domains** (93% of the Social & Forums category); **Trustpilot is 54% of the Review & Comparison category**. arXiv appears among public institutions at \~9% of that category.
* **Root domains beat URL paths.** Root-domain targeting pairs with broad informational terms (review, official, service, comparison); specific URL paths pair with product-specific and pricing queries. Product attributes (size, model names, colors) are the most common accompanying terms at 12%.

The pattern: root domains identify trusted sources; URL paths fire when the model already has a precise information need. Persistence of those domains and URLs over time: [ChatGPT fan-out domains vs URLs](/research/chatgpt-fanout-domains-vs-urls). The broader GPT-5.6 shift: [GPT-5.6 retrieval changes](/research/gpt-56-retrieval-changes).

**Source:** [Understanding site operator usage in ChatGPT 5.6 fan-outs](https://www.linkedin.com/pulse/understanding-site-operator-usage-chatgpt-56-fan-outs-david-konitzny-sycce/), David Konitzny, LinkedIn, Jul 2026.


# Citation rate benchmarks differ sharply by engine
Source: https://docs.peec.ai/research/citation-rate-benchmarks-by-engine

Peec analysed over 1M citations in Feb 2026 — a good citation rate is engine-specific, from 2.0+ on ChatGPT to 1.1–1.5 on Google AI Mode and 1.5–2.0 on Perplexity.

A "good" citation rate depends on the engine. Peec's Feb 2026 analysis of over 1 million citations ([full study](https://peec.ai/blog/citation-rate-benckmarks-from-over-1-million-citations)) recommends engine-specific benchmarks: **2.0+ for ChatGPT**, **1.1–1.5 for Google AI Mode**, and **1.5–2.0 for Perplexity**. Citation rate is how often a URL is cited per AI answer relative to how often it is retrieved (see [Retrieval vs citation](/research/retrieval-vs-citation)).

* **ChatGPT is generous.** 31% of URLs sit in the 2.0+ bucket, and those URLs account for 59% of all ChatGPT citations. Top-cited pages get disproportionately high visibility.
* **Google AI Mode is conservative and consistent.** Over 90% of URLs have a citation rate below 1.0. The sweet spot is the 1.0–1.5 band, where only 3% of URLs make up 12% of citations. Above 1.5 is exceptional.
* **Perplexity is a tale of two extremes.** 64% of URLs are never cited in answers (they appear only in the sidebar), while the 6% of URLs above 2.0 carry just under half of all Perplexity citations.

The dataset was harmonized — evenly split by query intent, all prompts non-branded — to give a balanced view. If content underperforms on Perplexity, cross-check ChatGPT and Google AI Mode: the same URLs often perform very differently per engine. Related: [Citation rate by prompt intent](/research/citation-rate-by-prompt-intent) and [Content types cited most by engine](/research/content-types-cited-most-by-engine).

**Source:** [What does a good citation rate look like? Benchmarks from over 1 million AI citations](https://peec.ai/blog/citation-rate-benckmarks-from-over-1-million-citations), Peec (Tom Wells), Feb 2026.


# Citation rate by prompt intent — informational and commercial win
Source: https://docs.peec.ai/research/citation-rate-by-prompt-intent

Peec's 1M-citation study (Feb 2026) — 10–11% of URLs on informational and commercial prompts reach the top citation bucket and carry 37% of citations; transactional prompts spread citations thinly.

Prompt intent changes how concentrated AI citations are. Peec's Feb 2026 analysis of over 1 million citations ([full study](https://peec.ai/blog/citation-rate-benckmarks-from-over-1-million-citations)) compared four intents: informational, navigational/local, commercial, and transactional.

* **Informational and commercial prompts reward repeat winners.** Around 10–11% of URLs land in the top citation-rate bucket (2.0+), and those URLs make up 37% of all citations. When users learn or compare options, LLMs cite the same pages repeatedly.
* **Navigational/local and transactional prompts do not concentrate.** For transactional queries users explore multiple product pages, and for navigational/local queries multiple provider pages, so no small set of URLs dominates.

Practical read: aim for the high-citation bucket on informational and commercial prompts, where a single strong page can compound; on transactional prompts, breadth of coverage matters more than one winning URL. Engine-level targets are in [Citation rate benchmarks by engine](/research/citation-rate-benchmarks-by-engine); which formats reach the top bucket is in [Content types cited most by engine](/research/content-types-cited-most-by-engine).

**Source:** [What does a good citation rate look like? Benchmarks from over 1 million AI citations](https://peec.ai/blog/citation-rate-benckmarks-from-over-1-million-citations), Peec (Tom Wells), Feb 2026.


# Content types cited most by engine — listicles, product and category pages
Source: https://docs.peec.ai/research/content-types-cited-most-by-engine

Peec's 1M-citation study (Feb 2026) — 52% of listicles hit ChatGPT's top citation bucket; Google AI Mode favors category and product pages at far lower rates; Perplexity is highly selective.

Content types earn very different citation rates per engine. Peec's Feb 2026 analysis of over 1 million citations ([full study](https://peec.ai/blog/citation-rate-benckmarks-from-over-1-million-citations)) measured which content types reach the high-citation bucket (2.0+ for ChatGPT, 1.5+ for Google AI Mode and Perplexity), filtering out types under 5% of the dataset.

* **ChatGPT — listicles dominate.** Listicles are just under one-fifth of all URLs and 52% of them are cited more than twice per answer. Product pages have high presence but weak citation performance.
* **Google AI Mode — no favorites, brand-owned content preferred.** No content type reaches "high presence, high citations." The top performer, category pages, sits just under 10% — roughly 5× lower than ChatGPT's listicles. Among its most-cited pages, AI Mode leans to official brand sources: category and product pages (homepages also ranked highly but fell under the presence cutoff).
* **Perplexity — extreme selectivity.** Listicles and articles reach the high-presence, high-citation zone, but at much lower rates than ChatGPT; only \~6% of all URLs reach the top bucket at all.

The takeaway is not "just do listicles" — it is that each engine rewards different formats, so benchmark per engine (see [Citation rate benchmarks by engine](/research/citation-rate-benchmarks-by-engine)). Note that GPT-5.6 later shifted ChatGPT retrieval toward product pages — see [GPT-5.6 retrieves product pages over listicles](/research/gpt-56-product-pages-vs-listicles). Why listicles fit AI answers structurally: [Why listicles get cited](/research/why-listicles-get-cited).

**Source:** [What does a good citation rate look like? Benchmarks from over 1 million AI citations](https://peec.ai/blog/citation-rate-benckmarks-from-over-1-million-citations), Peec (Tom Wells), Feb 2026.


# Deep Research's reading budget — navigation crowds out your content
Source: https://docs.peec.ai/research/deep-research-reading-budget

Peec's Deep Research logs (Jun 2026) — each page open returns only ~5–6k characters; on link-heavy pages just 33% of the first read is real content, so front-load the answer in plain HTML.

Every page ChatGPT Deep Research opens returns only a capped window of text — roughly 5,700 characters median on first read, \~8,000 max — never the whole page. Peec measured this from recorded session logs ([full study](https://peec.ai/blog/how-chatgpt-deep-research-reads-your-site-what-the-logs-reveal), Jun 2026). Every link on the page renders inline as a marker that spends characters from that same window, so navigation competes directly with your content:

* **Light navigation (under 20 links):** \~78% of the first read is real content.
* **Medium (20–59 links):** \~55% — nearly half the read goes to menus and markup; most pages sit here.
* **Heavy navigation (60+ links):** \~33% — two-thirds of the read is chrome before the agent reaches your answer.

"Skip to main content" links do not help: activating one requires a click, and the agent never clicks — it reads the link as text and keeps going through the menu. Source order is what fills the budget, not on-screen position: a nav rendered at top by CSS but sitting late in the HTML costs nothing.

The fixes (Jun 2026 findings): put the main answer in the first screen of HTML as plain text, keep the header slim, move mega-menus below the content in source order, and unblock `OAI-SearchBot`. A page the agent dismisses on first read almost never gets a second look — re-reads are earned by keyword `find` hits. Full pipeline mechanics: [How Deep Research reads your site](/research/how-deep-research-reads-your-site).

**Source:** [How ChatGPT Deep Research reads your site: What the logs reveal](https://peec.ai/blog/how-chatgpt-deep-research-reads-your-site-what-the-logs-reveal), Peec (David Konitzny), Jun 2026.


# DeepSeek shared chat links are indexed by Google
Source: https://docs.peec.ai/research/deepseek-shared-links-indexed

David Konitzny's analysis (Jul 2026) — DeepSeek's /share/ conversation URLs are Google-indexed; only 13.2% of observed queries triggered web search, and each triggered search generates five fan-outs.

DeepSeek's shared conversation links are indexed by Google and discoverable with a simple `site:` search on the /share/ directory. David Konitzny documented the mechanism ([full article](https://www.linkedin.com/pulse/when-ai-conversations-become-public-analysis-deepseek-david-konitzny-xn8ze/), Jul 2026): DeepSeek's share button warns that "anyone with the link can view" but never mentions the link can be indexed by search engines — repeating the ChatGPT incidents of 2024.

Usage findings from the indexed shared chats (small dataset, directional only, Jul 2026):

* Russian is the top language at 31% of observed shared links; English second at 20%.
* **Only 13.2% of observed queries triggered a web search** — most DeepSeek conversations run without retrieval. When search does trigger, **the system generates five fan-outs immediately**, dominated by year modifiers (2025/2026) and `site:` operators — the same patterns seen in other engines.
* Most users treat DeepSeek as a single-question tool; conversations mostly end before \~10 message exchanges.

Shared-link exposure is a web-wide pattern, not an AI-specific one, and those links can even enter AI retrieval pipelines — see [Shared URLs in AI retrieval](/research/shared-urls-in-ai-retrieval).

**Source:** [When AI conversations become public: an analysis of DeepSeek shared links](https://www.linkedin.com/pulse/when-ai-conversations-become-public-analysis-deepseek-david-konitzny-xn8ze/), David Konitzny, LinkedIn, Jul 2026.


# Fan-outs per prompt by engine — Perplexity 1.4, ChatGPT 2.1, Grok 6.8
Source: https://docs.peec.ai/research/fanouts-per-prompt-by-engine

Peec's 5M fan-out analysis (Apr 2026) — Perplexity simplifies queries, ChatGPT adds brands and comparisons, Grok runs a research brief with site: searches on Reddit in 10.5% of chats.

AI engines fan out very differently. Peec's analysis of 5 million query fan-outs across ChatGPT, Perplexity, and Grok (April 1–21, 2026, [full study](https://peec.ai/blog/patterns-we-see-in-chatgpt-query-fanouts)) measured both volume and strategy:

* **Perplexity (Sonar): 1.4 fan-outs per prompt.** Typically just strips filler and reruns a cleaner version of the same search — the least useful optimization signal.
* **ChatGPT: 2.1 fan-outs per prompt.** Stays close to the user's intent but injects brand names, product comparisons, and keywords like "best", "top", "reviews" — see [Words ChatGPT adds to fan-outs](/research/words-chatgpt-adds-to-fanouts).
* **Grok: 6.8 fan-outs per prompt** — more than triple ChatGPT. Treats a query as a research brief: broad start, then year modifiers, brand-vs-brand comparisons, and targeted source searches.

Grok's trusted-source behavior stands out (Apr 2026 data): it uses the `site:` operator in **18.3% of all chats**. Reddit appears in 10.5% of Grok chats, and 9 of 10 of those are `site:reddit.com` directives. Wirecutter and Consumer Reports appearances were 100% Grok-injected — never in the user's prompt.

Takeaway: ChatGPT and Grok fan-outs are the most useful signals for content optimization; Perplexity's give almost nothing to work with. Definition and RRF: [What is a query fan-out](/research/what-is-a-query-fanout).

**Source:** [Patterns we see in ChatGPT query fanouts](https://peec.ai/blog/patterns-we-see-in-chatgpt-query-fanouts), Peec (Tomek Rudzki), May 2026.


# Losing Google rankings kills AI search visibility too
Source: https://docs.peec.ai/research/google-rankings-affect-ai-visibility

Peec's analysis (Feb 2026) — when Grokipedia's Google rankings dropped, ChatGPT, AI Mode and AI Overviews cut its citations at the same time; ChatGPT and Grok both draw on Google Search.

A Google ranking loss carries over into AI search visibility. Peec's analysis ([full article](https://peec.ai/blog/the-real-risk-of-ai-generated-content), Feb 2026) traces the chain using the Grokipedia case: when Grokipedia lost Google visibility in late January/early February 2026, Malte Landwehr (Peec) tracked ChatGPT, Google AI Mode, and AI Overviews all reducing Grokipedia citations at exactly the same time.

Why one Google penalty spreads everywhere (Feb 2026 analysis):

* **AI Overviews & AI Mode:** Google's own AI features cite lower-ranked pages less often.
* **ChatGPT:** evidence shows it uses Google Search extensively, including Google Shopping for product recommendations — confirmed again in Sep 2026 via a Search Console spike test; see [Where ChatGPT search results come from](/research/chatgpt-search-result-providers).
* **Grok:** also uses Google Search.

LLMs ground their answers through search engines, so a site removed or demoted in Google (and Bing) loses the retrieval layer AI answers are built on. The most common self-inflicted cause of such drops is publishing low-quality AI content at scale — see [The real risk of AI-generated content](/research/ai-generated-content-risk). Note the nuance for ChatGPT specifically: its Deep Research retrieval runs on Bing, making Bing its own lever — see [How Deep Research reads your site](/research/how-deep-research-reads-your-site).

**Source:** [The real risk of AI-generated content](https://peec.ai/blog/the-real-risk-of-ai-generated-content), Peec (Tomek Rudzki), Feb 2026.


# GPT-5.6 retrieves product pages over listicles
Source: https://docs.peec.ai/research/gpt-56-product-pages-vs-listicles

David Konitzny's analysis (Aug 2026) — under GPT-5.6, listicles fell from 15.47% to 8.19% of retrieved pages while product pages lead at 16.39%, with daily product-page retrievals up 119%.

GPT-5.6 shifted ChatGPT retrieval toward first-party product content on transactional prompts. David Konitzny's analysis of the August 2026 rollout ([full article](https://www.linkedin.com/pulse/chatgpts-new-default-model-gpt-56-more-retrieval-content-konitzny-8htce/)):

* **Listicles fell from 15.47% to 8.19%** of retrieved pages — down 9.8% in absolute daily retrievals too.
* **Product pages lead at 16.39%** of retrieved sources, up **119% in daily retrievals**; in almost every case the retrieved domain is the brand or manufacturer itself.
* How-to guides, comparison pages, and homepages lost *share* but gained 20–50% in absolute daily retrievals — the pie grew (see [GPT-5.6 retrieval changes](/research/gpt-56-retrieval-changes)).

The driver is the `site:` operator: fan-outs like `site:dell.com XPS 13 laptop specifications Core Ultra 2026` directly target product, feature, and pricing pages on brand domains instead of aggregators.

What brands should do (per the analysis, Aug 2026): treat product, feature, pricing, and specification pages as first-class AI-visibility assets — clear, current, commercially complete — and make sure they are technically accessible to retrieval systems, since a blocked or JS-gated page makes even a targeted fan-out lead nowhere. Earlier ChatGPT-era citation baselines for content types: [Content types cited most by engine](/research/content-types-cited-most-by-engine).

**Source:** [ChatGPT's new default model GPT-5.6: More retrieval, more fan-outs, more first-party content](https://www.linkedin.com/pulse/chatgpts-new-default-model-gpt-56-more-retrieval-content-konitzny-8htce/), David Konitzny, LinkedIn, Aug 2026.


# GPT-5.6 retrieval changes — more iterations, double the sources
Source: https://docs.peec.ai/research/gpt-56-retrieval-changes

David Konitzny's analysis (Aug 2026) — with GPT-5.6, single fan-out prompts dropped from 94% to 43.5%, second iterations rose to 33.5%, and sources retrieved per prompt doubled from ~12 to ~24.

GPT-5.6 (Luna), ChatGPT's default model for Free and Go users since early August 2026, retrieves fundamentally differently from GPT-5.5. David Konitzny's analysis ([full article](https://www.linkedin.com/pulse/chatgpts-new-default-model-gpt-56-more-retrieval-content-konitzny-8htce/), Aug 2026) documents the shift:

* **Multi-iteration retrieval is the new default.** Prompts needing only a single query fan-out dropped from **94.0% (GPT-5.5) to 43.5% (GPT-5.6)**. Second iterations rose from \~5% to **33.5%**; three iterations from 0.1% to 7.4%; even 6–10+ iterations (7.2% combined) are now measurable. Some sessions resemble a lightweight Deep Research.
* **Sources retrieved per prompt doubled** from \~12 to \~24, expanding the pool of domains that can enter answers.
* **Fan-out patterns shifted:** the `site:` operator now appears in 23% of fan-outs (vs 0.3% before), "official" rose from \~5% to 9%, and the current year appears in 28.6%. "Best" fell from \~20% to 9.9% in *share*, but its absolute count stayed constant — the denominator grew.

The practical consequence: visibility metrics fluctuated during the rollout because more retrieval iterations mean more chances for domains to enter or leave answers. What GPT-5.6 retrieves also changed — product pages overtook listicles; see [GPT-5.6 retrieves product pages over listicles](/research/gpt-56-product-pages-vs-listicles) and [ChatGPT site-operator fan-outs](/research/chatgpt-site-operator-fanouts).

**Source:** [ChatGPT's new default model GPT-5.6: More retrieval, more fan-outs, more first-party content](https://www.linkedin.com/pulse/chatgpts-new-default-model-gpt-56-more-retrieval-content-konitzny-8htce/), David Konitzny, LinkedIn, Aug 2026.


# How AI search chooses passages — retrieval, reranking, generation
Source: https://docs.peec.ai/research/how-ai-search-chooses-passages

Peec's reranker guide (Aug 2026) — AI answers run query fan-out, hybrid retrieval merged with RRF, a reranker sieve, then generation; each stage fails differently, so diagnose the stage first.

AI search picks sources through a pipeline, and each stage fails differently. Peec's reranker guide ([full guide](https://peec.ai/blog/rerankers-for-geo-aeo-how-ai-search-chooses-passages-and-sources), Aug 2026) describes the common documented pattern:

1. **Query planning:** the prompt is rewritten and split into several searches — see [What is a query fan-out](/research/what-is-a-query-fanout).
2. **Retrieval (wide net):** keyword search (BM25) and vector search run together; result lists merge via Reciprocal Rank Fusion, rewarding documents that rank well in both. OpenAI's documented File Search works this way (800-token chunks, 400 overlap, hybrid search, optional reranker).
3. **Reranking (fine sieve):** a cross-encoder-style model reads each candidate passage against the query and re-scores the shortlist. Your page is often scored as *passages*, not one URL — a strong page can contain a weak candidate passage, which is why page-level SEO metrics cannot explain every citation win or loss.
4. **Generation:** the LLM writes from the surviving passages and may cite some.

The diagnostic rule (Aug 2026): **not retrieved** → indexing, coverage, authority, or freshness problem; **retrieved but losing** → answer shape or passage relevance; **strong passage but no citation** → source quality, diversity rules, or generation-stage behavior. Fix the failed stage first — rewriting a paragraph for the reranker cannot fix a page that was never retrieved. What to actually write once diagnosed: [Answer shape for AI citations](/research/answer-shape-for-ai-citations).

**Source:** [Rerankers for GEO/AEO: How AI search chooses passages and sources](https://peec.ai/blog/rerankers-for-geo-aeo-how-ai-search-chooses-passages-and-sources), Peec (Metehan Yesilyurt), Aug 2026.


# How ChatGPT Deep Research reads your site — Bing, three commands, no clicks
Source: https://docs.peec.ai/research/how-deep-research-reads-your-site

Peec recorded Deep Research's logs (Jun 2026) — the agent runs on Bing snippets (~285 chars), three text-browser commands (search, open, find), never clicks, and obeys OAI-SearchBot rules.

ChatGPT Deep Research narrates its whole session over a recordable WebSocket, and Peec recorded it across 10+ accounts and \~200 runs ([full study](https://peec.ai/blog/how-chatgpt-deep-research-reads-your-site-what-the-logs-reveal), Jun 2026). The mechanics (this covers Deep Research's text browser, not quick Search or Agent mode):

* **Three commands, never a click.** `search` (Bing), `open` (skim a page as numbered plaintext), `find` (Ctrl+F inside the open page). `click` was used zero times across every logged session — content reachable only via JavaScript, accordions, tabs, or filters does not exist for the agent. Client-rendered SPAs are hit hardest.
* **All retrieval runs on Bing** (`web_with_bing`), no Google fallback. Bing snippets cap at \~285 characters — the entire window you get to earn the open. For ChatGPT, only the top 2–3 Bing results per query make the read set once the agent is confident (its `topn` depth parameter narrows from 10 to 2–3 as it converges).
* **The read is your HTML, linearized top-to-bottom** in source order, `<head>` stripped, nothing JS-rendered. It follows links — including internal ones — by reading the href from inline link markers, so descriptive anchor text routes it to pricing and spec pages.
* **Blocked means invisible.** `robots.txt` blocks on `OAI-SearchBot` return zero content (this is a different bot from GPTBot, which governs training — see [AI bot types](/research/ai-bot-types)). Login walls, bot-refusing marketplaces, and timeouts silently drop sources.
* **Re-reads are keyword-driven:** the top trigger is a successful `find` — the agent re-opens the page positioned on the matched line (95% of the time in the sample). Use the exact words people search, verbatim, in headings and copy.

How much of your page fits in each read, and why navigation costs you: [Deep Research reading budget](/research/deep-research-reading-budget). Exact figures are a June 2026 snapshot; the mechanics are the durable finding.

**Source:** [How ChatGPT Deep Research reads your site: What the logs reveal](https://peec.ai/blog/how-chatgpt-deep-research-reads-your-site-what-the-logs-reveal), Peec (David Konitzny), Jun 2026.


# Kimi's content strategy — retrieved often, recommended rarely
Source: https://docs.peec.ai/research/kimi-ai-visibility-content-strategy

David Konitzny's case study (Jul 2026) — Kimi mass-published listicles and how-tos (882 pages in one day) and hit top-5 retrieval (11.2% share), but only 5% brand visibility vs Claude's 15%.

Kimi (Moonshot AI's assistant) ran a textbook AI-visibility content play — and its results show that being retrieved is not the same as being recommended. David Konitzny's case study ([full article](https://www.linkedin.com/pulse/kimi-using-ai-visibility-content-strategy-david-konitzny-ymwze/), Jul 2026):

* **The play:** mass uploads of listicles and how-to articles on kimi.com — 882 pages live on a single day (June 6, 2026; 52% how-tos, 27% listicles), two more bulk uploads around the Kimi 3 release (July 16, 2026), all translated into six-plus languages. Kimi ranked itself #1 in its own "Top 10 AI App Builders" listicle.
* **Retrieval worked fast:** within weeks Kimi ranked top-5 among retrieved sources across matched prompts with an **11.2% retrieval share**, driven almost exclusively by the new pages. Retrieval was strongest in Italy and Germany (multilingual entry points), just 0.8% in the US.
* **Brand visibility lagged:** Kimi ranked only sixth in actual brand mentions at **5% visibility share**, versus Claude's 15%. Model differences were large — Gemini mentioned Kimi at 3%, ChatGPT at just 0.4%.

The takeaway: large-scale, AI-focused content can enter LLM retrieval pipelines within weeks, but retrieval visibility does not automatically convert into brand recommendations — track both separately. Metric definitions: [Retrieval vs citation](/research/retrieval-vs-citation).

**Source:** [Is Kimi using an AI visibility content strategy?](https://www.linkedin.com/pulse/kimi-using-ai-visibility-content-strategy-david-konitzny-ymwze/), David Konitzny, LinkedIn, Jul 2026.


# Listicle rank effect — position in cited listicles shapes AI visibility
Source: https://docs.peec.ai/research/listicle-rank-effect-on-visibility

Peec's 200K-response study (Sep 2025–Mar 2026) — rank #1 in AI-cited third-party listicles lifts brand mention probability up to +16.5pp and moves brands up to 1.8 positions earlier in the answer.

A brand's position inside AI-cited third-party listicles is strongly associated with how AI engines present that brand. Peec analyzed nearly 200,000 AI responses — over 5.7 million data points across eight engines and three markets (B2B SaaS, Emerging MarTech, US Finance), collected September 2025 to March 2026 ([full study](https://peec.ai/blog/the-listicle-rank-effect-what-nearly-200-000-ai-responses-across-8-ai-engines-reveal-about-brand-visibility)).

* **Visibility:** Being in a frequently cited third-party listicle strongly raises mention probability. Rank #1 lifts: B2B SaaS +16.5pp, Emerging MarTech +13.4pp. Rank matters most in emerging/fragmented categories where engines have weak prior knowledge; in established B2B SaaS, inclusion matters more than exact rank; in sparse US Finance, a few trusted listicles carry outsized weight regardless of position.
* **Answer position (the most consistent effect):** Rank #1 exposure moves a brand earlier in the answer — US Finance 1.80 positions, B2B SaaS 1.17, Emerging MarTech 0.82 — consistent across all three markets.
* **Mention count:** Diverges by market (Emerging MarTech +0.67, B2B SaaS +0.43, US Finance +0.66 but statistically insignificant). Track visibility, position, and mention count as three separate metrics.

Caveats: observational associations, not causal proof; findings apply to *frequently retrieved* third-party listicles, not every listicle, and self-authored listicles were excluded. Methodology in the companion paper ([SSRN working paper](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6753841), May 2026). Engine differences and how many listicles are enough: [Listicle strategy by engine](/research/listicle-strategy-by-engine).

**Source:** [The Listicle Rank Effect: What nearly 200,000 AI responses across 8 AI engines reveal about brand visibility](https://peec.ai/blog/the-listicle-rank-effect-what-nearly-200-000-ai-responses-across-8-ai-engines-reveal-about-brand-visibility), Peec (Jan Ehrlinspiel), May 2026.


# Listicle strategy by engine — few placements beat many
Source: https://docs.peec.ai/research/listicle-strategy-by-engine

Peec's 200K-response study (2025–2026) — listicle impact plateaus after a few placements, and tighter-retrieval engines like ChatGPT and Copilot reward top ranks more than Google's surfaces.

Winning a few AI-cited listicles beats being in many. Peec's study of nearly 200,000 AI responses across eight engines (September 2025–March 2026, [full study](https://peec.ai/blog/the-listicle-rank-effect-what-nearly-200-000-ai-responses-across-8-ai-engines-reveal-about-brand-visibility)) found two strategy-level results:

* **Diminishing returns.** Maximum impact is often reached after just a few repeated placements in frequently cited listicles. Five strong placements in listicles AI engines actually retrieve matter more than 50 placements in articles engines never see. The goal is not "get listed everywhere" — it is winning the few listicles engines actually cite for your prompts.
* **Engines weight citations differently.** Engines with tighter source retrieval (ChatGPT, GPT-5 Search, Microsoft Copilot) showed larger visibility lifts from top-ranked listicle placements — fewer sources, more weight per citation. Broad-retrieval engines (Google AI Overview, Google AI Mode) showed smaller individual lifts, so casting a slightly wider net across multiple trusted sources helps there.

The playbook: diagnose market structure first (fragmented markets reward rank most), track responses per engine, identify which listicles engines actually retrieve, prioritize gaps where competitors appear and you do not, and give publishers evidence (comparison pages, reviews, pricing) to justify placement. Effect sizes per rank tier: [Listicle rank effect on visibility](/research/listicle-rank-effect-on-visibility). Why the format wins structurally: [Why listicles get cited](/research/why-listicles-get-cited).

**Source:** [The Listicle Rank Effect: What nearly 200,000 AI responses across 8 AI engines reveal about brand visibility](https://peec.ai/blog/the-listicle-rank-effect-what-nearly-200-000-ai-responses-across-8-ai-engines-reveal-about-brand-visibility), Peec (Jan Ehrlinspiel), May 2026.


# Most-cited domains by engine — top 5 sources per AI platform
Source: https://docs.peec.ai/research/most-cited-domains-by-engine

Peec's 30M-source analysis (Mar 2026) — Reddit and YouTube lead everywhere; Google's surfaces favor social (Facebook, Yelp), ChatGPT favors editorial (Forbes, Techradar), G2 only for Perplexity.

Each AI engine trusts a different top-source mix. From Peec's 30-million-source US analysis ([full study](https://peec.ai/blog/top-domains-cited-by-ai-search-analysis-based-on-30m-sources), Mar 2026), the top 5 cited domains per platform:

| Platform | Top 5 sources |
| - | - |
| Google AI Mode | YouTube, Reddit, Facebook, LinkedIn, Yelp |
| AI Overviews | YouTube, Reddit, Facebook, LinkedIn, Medium |
| Gemini | Reddit, YouTube, Wikipedia, Medium, PCMag / Forbes |
| Perplexity | Reddit, YouTube, LinkedIn, Wikipedia, G2 |
| ChatGPT | Wikipedia, Reddit, Forbes, Techradar, LinkedIn |

Patterns worth acting on (Mar 2026 data):

* **Reddit and YouTube appear in all five platforms' top 5** — the only universal signals.
* **Google's AI Mode and AI Overviews favor social content** (Facebook, Yelp); **ChatGPT leans editorial** (Forbes, Techradar).
* **Wikipedia is strong for ChatGPT and Perplexity but absent from Google's top 5.**
* **G2 appears only for Perplexity** — relevant for B2B teams.
* Facebook blocks Perplexity's bots entirely (robots.txt), so Facebook presence is a dead end for that channel; it still matters as diversification on Google's surfaces.

Overall cross-engine ranking: [Most-cited domains in AI search](/research/most-cited-domains-in-ai-search).

**Source:** [Top domains cited by AI search: Analysis based on 30M sources](https://peec.ai/blog/top-domains-cited-by-ai-search-analysis-based-on-30m-sources), Peec (Tomek Rudzki), Mar 2026.


# Most-cited domains in AI search — Reddit, YouTube, LinkedIn lead
Source: https://docs.peec.ai/research/most-cited-domains-in-ai-search

Peec's 30-million-source analysis (Mar 2026, US) ranks the top 10 domains cited across ChatGPT, Google AI Mode, Gemini, Perplexity and AI Overviews: Reddit #1, YouTube #2, LinkedIn #3, Wikipedia #4.

Reddit is the most-cited domain in AI search. Peec analyzed 30 million cited sources across ChatGPT, Google AI Mode, Gemini, Perplexity, and AI Overviews in the US ([full study](https://peec.ai/blog/top-domains-cited-by-ai-search-analysis-based-on-30m-sources), Mar 2026), counting only sources directly cited in answers.

Top 10 most-cited domains (Mar 2026):

1. Reddit.com
2. YouTube.com
3. LinkedIn.com
4. Wikipedia.org
5. Forbes.com
6. G2.com
7. Yelp.com
8. Facebook.com
9. Medium.com
10. Techradar.com

The generic list is a starting point, not a strategy: industries have their own dominant sources (in hotels, Booking.com and Airbnb often outrank Reddit). Per-platform rankings differ meaningfully — see [Most-cited domains by engine](/research/most-cited-domains-by-engine) — and individual platforms have their own dynamics: [Reddit in AI search](/research/reddit-in-ai-search), [YouTube in AI search](/research/youtube-in-ai-search), [Wikipedia in AI search](/research/wikipedia-in-ai-search), [Review sites in AI search](/research/review-sites-in-ai-search).

**Source:** [Top domains cited by AI search: Analysis based on 30M sources](https://peec.ai/blog/top-domains-cited-by-ai-search-analysis-based-on-30m-sources), Peec (Tomek Rudzki), Mar 2026.


# Optimizing for Google AI Overviews and AI Mode vs ChatGPT — 5 differences
Source: https://docs.peec.ai/research/optimizing-google-ai-vs-chatgpt

Peec's research (2026) — Google's AI surfaces promote YouTube and render JavaScript; ChatGPT retrieves via its own index and providers with RRF fan-outs, skips JS; both lean on Reddit.

Google's AI ecosystem (AI Overviews, AI Mode, Gemini) and ChatGPT use different ranking signals, trust different sources, and reward different optimization strategies. Peec's 500,000-prompt AI Overviews study ([full study](https://peec.ai/blog/ai-overviews-is-the-most-undertracked-ai-search-500-000-prompts-show-why), published 2026) names five differences, drawing on Peec's earlier 30-million-source analysis:

1. **AI Overviews heavily promotes YouTube.** Video content is a direct pathway into Google's AI surfaces that ChatGPT does not offer — see [YouTube in AI search](/research/youtube-in-ai-search).
2. **ChatGPT does not render JavaScript.** JS-heavy sites (React, Vue) are unreadable to ChatGPT but readable to Google — a structural advantage for AI Overviews on JS stacks.
3. **ChatGPT uses Reciprocal Rank Fusion (RRF).** It fans your prompt out into multiple sub-queries and combines results, so winning means appearing across many related queries, not ranking for one — see [What is a query fan-out](/research/what-is-a-query-fanout). ChatGPT's retrieval is not just Bing: it blends its own index with Google, Bing and other providers — see [Where ChatGPT search results come from](/research/chatgpt-search-result-providers).
4. **Both ecosystems lean heavily on Reddit.** The one consistent signal across both — see [Reddit in AI search](/research/reddit-in-ai-search).
5. **Non-English markets are harder in ChatGPT.** ChatGPT mixes English and local-language sources even for non-English prompts, while AI Overviews stays closer to the query language — see [ChatGPT searches in English](/research/chatgpt-searches-in-english).

The two systems share some signals (Reddit presence, content quality, citations) but diverge enough that one combined strategy underperforms on both; the study recommends separate tracking and optimization per surface.

**Source:** [AI Overviews is the most undertracked AI search: 500,000 prompts show why](https://peec.ai/blog/ai-overviews-is-the-most-undertracked-ai-search-500-000-prompts-show-why), Peec (Tomek Rudzki), May 2026.


# Prompt style changes how many brands AI answers show
Source: https://docs.peec.ai/research/prompt-style-and-brand-visibility

Peec's 37,804-response study (2026) — ranking/list prompts surface ~20% more brands and keyword-style prompts up to 25% more than open-ended questions; filler length has zero effect.

How a prompt is styled — not just what it means — changes which brands AI engines surface. From Peec's study of 1,754 prompts and 37,804 AI responses across ChatGPT, Gemini, Perplexity, Google AI Mode, and AI Overviews ([published study](https://www.searchenginejournal.com/ai-prompt-intent-keywords-peec-spa/576201/), 2026):

* **Format matters:** asking for a comparison, table, list, or ranking consistently surfaces more brands; a ranking prompt adds about **+20% average visibility** over open-ended questions.
* **Keywords beat conversation:** concise keyword-style prompts ("best CRM small business 2026") yield up to **+25% more brand mentions** than persona-engineered prompts ("You are an IT consultant…"), which broaden into less brand-dense educational paths.
* **Constraints split by engine:** adding budget or feature constraints reduces the brands shown in ChatGPT and Perplexity but *increases* them in Gemini and Google AI Overviews — potentially by triggering extra fan-out queries.
* **Length is irrelevant:** filler and conversational words have effectively zero impact on which brands appear.

For tracking, tag prompts by format — a list prompt and an open-ended prompt do not share a baseline, so mixing styles muddies trends. The wording-similarity thresholds behind the same study: [Prompt wording and AI visibility](/research/prompt-wording-and-ai-visibility).

**Source:** [How prompt wording impacts AI brand visibility](https://www.searchenginejournal.com/ai-prompt-intent-keywords-peec-spa/576201/), Peec via Search Engine Journal, 2026.


# Rewording of a prompt rarely changes AI visibility until cosine similarity drops
Source: https://docs.peec.ai/research/prompt-wording-and-ai-visibility

Peec's study of 37,804 AI responses (2026) — AI visibility holds while prompt variants stay above ~0.50–0.60 cosine similarity; below that brand mentions drop ~50%, hitting middle-of-funnel hardest.

Rewording a prompt barely changes which brands AI engines mention — until the rephrasing drifts past a measurable semantic threshold. Peec analyzed 1,754 prompts and 37,804 AI responses across five engines and 18 subverticals ([published study](https://www.searchenginejournal.com/ai-prompt-intent-keywords-peec-spa/576201/), 2026; methodology in the [SSRN working paper](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6914539), Jun 2026), using two designs: 288 human-written prompts, and controlled variants stepped in tiny cosine-similarity intervals.

* **Human phrasing only looks chaotic.** \~88–92% of human prompt pairs for the same commercial need sit above 0.50 cosine similarity; \~95% above 0.40. Less than 10% of variations drift semantically far.
* **Mentions hold above the threshold.** As long as variants stay above \~0.50–0.60 similarity (engine-dependent), brand mentions stay stable. In the lowest bin (0.35–0.39), mention probability drops 2.40 percentage points against a 4.9% baseline — roughly a 50% relative decrease.
* **Middle-of-funnel is the sensitive zone.** Unbranded commercial discovery prompts ("best CRMs for a small remote team") drop off as early as the 0.60–0.65 bucket; top-of-funnel and branded bottom-of-funnel prompts are stable. Suggested tracking split: \~25% TOFU, 50% MOFU, 25% BOFU.
* **Beware the semantic blindspot:** "car rental Munich" vs "car rental Frankfurt" are 95% similar but different intents — a changed qualifier (location, product, demographic, brand) is a new intent.
* **Engines differ:** Google AI Overviews shows the most persistent MOFU sensitivity; Gemini's effect fades fastest — report engines separately.

Takeaway (2026): prompt tracking works, but not as a one-prompt measurement system — track a portfolio across semantic neighborhoods, funnel stages, and engines. How prompt *style* shifts baselines: [Prompt style and brand mentions](/research/prompt-style-and-brand-visibility).

**Source:** [How prompt wording impacts AI brand visibility](https://www.searchenginejournal.com/ai-prompt-intent-keywords-peec-spa/576201/), Peec via Search Engine Journal, 2026.


# Being read is not being cited — AI agents read far more than they cite
Source: https://docs.peec.ai/research/read-vs-cited-in-deep-research

Peec's Deep Research logs (Jun 2026) — ChatGPT's agent reads many pages that never appear as sources, so citation counts undercount real influence on the answer; trust judgments mirror E-E-A-T.

ChatGPT's Deep Research agent reads far more pages than it cites. Peec's recorded session logs ([full study](https://peec.ai/blog/how-chatgpt-deep-research-reads-your-site-what-the-logs-reveal), Jun 2026) show reading builds the agent's understanding, while citing is a separate later decision it often declines — its own words: "the site doesn't have specific content to cite for closures, so I'll rely on general knowledge, as no citation is required here."

Consequences for measurement (Jun 2026 findings):

* **A page can shape the answer without appearing as a source.** Tracking citations alone undercounts real influence.
* **Getting opened is necessary but not sufficient.** To be cited you must be the specific, non-obvious source for a claim the agent decides needs backing.
* **Trust is graded before reading.** The logs show consistent vocabulary: positive signals cluster around "official, reliable, trusted, credible, reputable"; user-generated and forum content is kept as background context, not primary evidence. The pattern mirrors E-E-A-T — be the official source in your category, or earn citations from it.

The retrieval-level analogue of this gap — retrieved but not cited — has its own metric and benchmarks: [Retrieval vs citation](/research/retrieval-vs-citation). A case study of the gap at brand level: [Kimi's content strategy](/research/kimi-ai-visibility-content-strategy).

**Source:** [How ChatGPT Deep Research reads your site: What the logs reveal](https://peec.ai/blog/how-chatgpt-deep-research-reads-your-site-what-the-logs-reveal), Peec (David Konitzny), Jun 2026.


# Reddit in AI search — the most-cited domain
Source: https://docs.peec.ai/research/reddit-in-ai-search

Peec's 30M-source analysis (Mar 2026) found Reddit is the #1 most-cited domain in AI answers, ranking first or second on every engine tested; AI engines trust its authentic user discussions.

Reddit is the most-cited domain in LLM responses. In Peec's 30-million-source US analysis ([full study](https://peec.ai/blog/top-domains-cited-by-ai-search-analysis-based-on-30m-sources), Mar 2026), Reddit ranked #1 or #2 on every AI engine tested — ChatGPT, Google AI Mode, Gemini, Perplexity, and AI Overviews.

Why AI engines trust it: Reddit captures authentic user experiences and discussions that read as more trustworthy than marketing content — real people asking real questions and getting real answers. Practical guidance from the study: monitor what Reddit says about your brand, and participate only authentically, adding real value.

Reddit's pull shows up beyond citations too (2026 data):

* Grok deliberately targets Reddit with `site:reddit.com` searches in 10.5% of its chats — see [Fan-outs per prompt by engine](/research/fanouts-per-prompt-by-engine).
* Reddit is 71% of the non-branded domains ChatGPT targets with the site: operator — see [ChatGPT site-operator fan-outs](/research/chatgpt-site-operator-fanouts).
* On Google's AI surfaces in non-English markets, 40–73% of Reddit citations point to Reddit's own machine-translated pages — see [Translated Reddit citations](/research/reddit-translated-citations).

One diversification caveat from the study: both Google and ChatGPT have historically gone through periods of pulling back from Reddit, so brands with a Reddit-only community presence carry concentration risk.

**Source:** [Top domains cited by AI search: Analysis based on 30M sources](https://peec.ai/blog/top-domains-cited-by-ai-search-analysis-based-on-30m-sources), Peec (Tomek Rudzki), Mar 2026.


# Translated Reddit is winning AI citations on Google's surfaces
Source: https://docs.peec.ai/research/reddit-translated-citations

Peec analysed 64.77M Reddit citations (Mar–Jun 2026) — on Google's AI surfaces, 40–73% of Reddit citations in non-English markets are machine-translated pages; ChatGPT cut its share to 0.30%.

Reddit's machine-translated pages (URLs carrying the `?tl=` parameter) are taking over Reddit citations on Google's AI surfaces in non-English markets. Peec analyzed 64.77 million Reddit citations across 20 countries and four engines, March 1–June 10, 2026 ([full study](https://peec.ai/blog/reddit-machine-translated-pages-ai-visibility)); 3.7 million citations (5.71%) carried `?tl=`.

* **Google cites translations at industrial scale.** Google AI Overview served translated Reddit in 52% of its German Reddit citations, over 70% in Sweden and Norway; Google AI Mode hit 72% in Spain in early June 2026. Across non-English markets both Google products run 40–73%.
* **ChatGPT went the other way.** Its translated share dropped from 6.14% (April 2026) to 0.66% (May) and 0.30% (early June) — consistent across countries (Germany 18.06%→1.54%). Something changed on OpenAI's side around late April/early May 2026.
* **Gemini barely touches translations (\~1%); Perplexity is a structural zero** — never a single `?tl=` citation in the period.
* **The split is clean:** English-speaking markets (US, UK, AU, IN) under 1%; non-English markets 24–42% of Reddit citations.
* In Germany the translated citations sit in commercial categories — fashion, tech hardware, audio, gaming, automotive, SaaS — and single threads can collect five-figure citation counts.

Implication: on Google's AI surfaces the language barrier protecting local-language content is functionally gone, and the same question can pull translated English Reddit on AI Mode but original threads on ChatGPT — measure per engine and per market. Background on Reddit's overall dominance: [Reddit in AI search](/research/reddit-in-ai-search).

**Source:** [Translated Reddit is winning AI citations](https://peec.ai/blog/reddit-machine-translated-pages-ai-visibility), Peec (Metehan Yesilyurt), Jun 2026.


# Writing in reranker-friendly chunks is mostly a myth
Source: https://docs.peec.ai/research/reranker-friendly-chunks-myth

Peec's reranker guide (Aug 2026) — you cannot control how AI systems chunk your page and overlap absorbs boundary damage; write locally self-contained sections with one direct-answer sentence instead.

Writing content to match AI "chunk boundaries" optimizes a target you cannot see. Peec's reranker guide ([full guide](https://peec.ai/blog/rerankers-for-geo-aeo-how-ai-search-chooses-passages-and-sources), Aug 2026) separates the myth from the insight:

The myth (Aug 2026):

* **You cannot control the chunks.** OpenAI File Search cuts at 800 tokens with 400 overlap; other systems cut at 256 or 512 tokens, sentence boundaries, or character counts; web pipelines use whatever the snippet extractor produced.
* **Chunk boundaries are rarely fatal** — 50% overlap means a good answer sentence cut in one window survives intact in the next.
* **Rewriting every paragraph as a self-contained answer machine produces robotic text** humans stop reading — and humans still assign the links and mentions that get you retrieved at all.

What actually helps:

* **Local self-containedness:** any few-hundred-word window of the page should make sense alone — name things explicitly instead of "it/this tool", keep the answer near its subject.
* **One direct-answer sentence per target question** — the highest-leverage edit measured; see [Answer shape for AI citations](/research/answer-shape-for-ai-citations).

Where chunk-conscious structure pays off: long guides, docs, and pages targeting many distinct queries. Where it wastes effort: short pages (one chunk anyway), branded queries, unique original data, and conversion pages whose job is persuading humans, not being cited.

**Source:** [Rerankers for GEO/AEO: How AI search chooses passages and sources](https://peec.ai/blog/rerankers-for-geo-aeo-how-ai-search-chooses-passages-and-sources), Peec (Metehan Yesilyurt), Aug 2026.


# Retrieval vs citation — the difference and why it matters
Source: https://docs.peec.ai/research/retrieval-vs-citation

A retrieval means a page entered the candidate set for an AI answer; a citation means the answer used and referenced it. Peec's 1M-citation study (Feb 2026) defines the ratio as citation rate.

Retrieval and citation are two different events in AI search, defined in Peec's Feb 2026 study of over 1 million citations ([full study](https://peec.ai/blog/citation-rate-benckmarks-from-over-1-million-citations)). A **retrieval** is when a webpage is fetched by the LLM and makes it into the candidate set the model might use. A **citation** is when that page is actually used and clearly referenced in the AI answer. The relationship between the two is the **citation rate** — on average, how often a URL is cited per answer.

Why the distinction matters:

* Being retrieved is necessary but not sufficient. On Perplexity, 64% of retrieved URLs are never cited in the answer at all (Feb 2026 data).
* Retrieval and brand visibility diverge too: in a Jul 2026 analysis, Kimi ranked top-5 as a retrieved source (11.2% retrieval share) but only sixth in brand mentions — see [Kimi's AI visibility content strategy](/research/kimi-ai-visibility-content-strategy).
* ChatGPT's Deep Research agent reads far more pages than it cites — see [Being read is not being cited](/research/read-vs-cited-in-deep-research).

For benchmarks on what a good citation rate looks like per engine — ChatGPT 2.0+, Google AI Mode 1.1–1.5, Perplexity 1.5–2.0 — see [Citation rate benchmarks by engine](/research/citation-rate-benchmarks-by-engine).

**Source:** [What does a good citation rate look like? Benchmarks from over 1 million AI citations](https://peec.ai/blog/citation-rate-benckmarks-from-over-1-million-citations), Peec (Tom Wells), Feb 2026.


# Review sites in AI search — Yelp, G2, Trustpilot shape recommendations
Source: https://docs.peec.ai/research/review-sites-in-ai-search

Peec's 30M-source analysis (Mar 2026) — Yelp, Tripadvisor, Trustpilot, G2 and Clutch all rank in the top 100 cited domains; when AI needs to recommend something, it reads review platforms.

Review platforms quietly shape AI recommendations. In Peec's 30-million-source US analysis ([full study](https://peec.ai/blog/top-domains-cited-by-ai-search-analysis-based-on-30m-sources), Mar 2026), Yelp ranks #7 among all cited domains, and the top 100 includes Tripadvisor, Trustpilot, G2, and Clutch — each serving a different category, from local and hospitality to B2C services and B2B software.

The pattern is consistent: **when AI needs to recommend something, it looks at review platforms.** A business listed on any of them likely has its profile influencing how AI talks about it — so that presence should be accurate, complete, and actively maintained.

Supporting evidence from other 2026 Peec research:

* G2 appears in Perplexity's top 5 sources — see [Most-cited domains by engine](/research/most-cited-domains-by-engine).
* Trustpilot is 54% of the review-category domains ChatGPT targets with the site: operator — see [ChatGPT site-operator fan-outs](/research/chatgpt-site-operator-fanouts).
* ChatGPT injects "reviews" into its hidden searches even when users never ask for reviews, and smaller review sites (e.g. Sitejabber) can drive how AI describes a brand — see [Words ChatGPT adds to fan-outs](/research/words-chatgpt-adds-to-fanouts).

**Source:** [Top domains cited by AI search: Analysis based on 30M sources](https://peec.ai/blog/top-domains-cited-by-ai-search-analysis-based-on-30m-sources), Peec (Tomek Rudzki), Mar 2026.


# Self-promotional listicles still get cited — about 1 in 10 citations
Source: https://docs.peec.ai/research/self-promotional-listicles

Peec's 232,000-citation study (Dec 2025–Feb 2026) — ~11% of AI search citations come from self-promotional listicles; ChatGPT filters best at ~3.6% vs ~10% for Google AI Mode and Perplexity.

AI search has not solved the self-promotion problem. Peec analyzed 232,000 citations across 13,000 listicles over 12 weeks (December 2025–February 2026) on six platforms in the software-review niche ([full study](https://peec.ai/blog/self-promotional-listicles-analysis-from-232k-citations)). A self-promotional listicle is a "best of" roundup where the publishing brand ranks its own product on top.

* **\~11% of citations** come from self-promotional listicles — roughly 1 in 10.
* **No evidence of algorithmic correction** over the 12 weeks: rates stayed stable within natural variation, so any corrections brands see are case-by-case, not systemic.
* **ChatGPT filters best by far:** 3.6% average — about 3× lower than Google AI Mode (10.3%) and Perplexity (10.4%). Likely drivers: ChatGPT draws from more diverse sources, uses more educational sites in this niche (7.8% vs 3.6% Perplexity, 2.5% AI Mode), and uses Zapier far less (\~1% of URLs vs \~8%).

Despite still "working," the study recommends against the tactic: reputational risk, explicit algorithmic warnings from SEO voices like Lily Ray, and better alternatives — earning placements in third-party listicles (see [Listicle rank effect on visibility](/research/listicle-rank-effect-on-visibility)), review-site relationships, and educational content.

**Source:** [Self-promotional listicles analysis: Data from 232,000 citations](https://peec.ai/blog/self-promotional-listicles-analysis-from-232k-citations), Peec (Tom Wells), Mar 2026.


# Server logs for AI search — diagnose crawled-but-not-cited pages
Source: https://docs.peec.ai/research/server-logs-for-ai-search

Peec's guide (Jun 2026) — server logs show whether AI bots can reach you and which pages they request; pages crawled often but rarely cited point to technical, quality, or prompt-tracking gaps.

Server logs are the most direct way to see why AI search visibility underperforms. Peec's guide ([full guide](https://peec.ai/blog/why-server-logs-are-crucial-for-ai-search-strategy), Jun 2026) sets the check order:

1. **Crawlability first.** A bot blocked in robots.txt cannot help you, no matter how good the page is. Rule access out before tuning anything downstream.
2. **All three bot types present** — training, search, and user-query bots each map to a different visibility stage; a missing type names the gap. See [AI bot types](/research/ai-bot-types).
3. **Cross crawls against citations.** The real insight comes from combining how often bots request a page with whether it shows up as a source.

A page crawled often but rarely cited points to one of three different problems, each with a different fix (Jun 2026 guidance):

* **Technical:** bots reach the page but heavy JavaScript blocks clean parsing.
* **Content quality:** accessible, but LLMs choose not to include it.
* **Prompt-tracking gap:** the page performs well on prompts you are not tracking — broaden coverage using the topics the crawled page covers.

Also check where bots land, not just how often: bots hitting only the homepage and top-level pages signal a crawl-depth or internal-linking issue — a page that never appears in logs cannot be fixed by content tuning.

**Source:** [Why server logs are crucial for AI search strategy](https://peec.ai/blog/why-server-logs-are-crucial-for-ai-search-strategy), Peec (Tomek Rudzki), Jun 2026.


# Shared URLs and leaked chats in AI retrieval — rare but real
Source: https://docs.peec.ai/research/shared-urls-in-ai-retrieval

David Konitzny's analysis (Jul 2026) — shared Google Docs URLs are 0.000217% of URLs in AI retrieval but do appear; Perplexity reuses a found Docs link 5–8× more consistently than other engines.

Leaked AI chats and shared document URLs do enter AI retrieval pipelines — at microscopic rates. David Konitzny analyzed the 2026 wave of indexed shared chats (Claude, DeepSeek, following ChatGPT in 2024) and traced shared URLs into retrieval ([full article](https://www.linkedin.com/pulse/beyond-ai-chat-leaks-hidden-risk-shared-urls-age-david-konitzny-yrodc/), Jul 2026):

* The mechanism is old web behavior, not an AI flaw: share features generate public URLs, search engines index them — Google Docs and Dropbox links included. DuckDuckGo and Brave often keep them indexed longer than Google.
* **Shared Google Docs URLs are 0.000217% of all URLs in AI retrieval** — statistically negligible, but present. Each engine favors a file type: Google AI Overviews surfaces Documents, ChatGPT Presentations, Perplexity Spreadsheets.
* **Reuse differs sharply by engine (Jul 2026 data).** For 68.9% of affected prompts the Docs link is a one-off random hit. But **Perplexity's reuse rates are 5–8× higher** than other engines — one in eight affected Perplexity prompts reuses the same Docs URL in over half its chats (median 76.9%). Google AI Overview shows the opposite: broadest discovery, lowest stickiness (1.52%).

Takeaway: engines differ not just in what they retrieve but in how consistently they reuse discovered sources. The DeepSeek-specific indexing case: [DeepSeek shared links indexed](/research/deepseek-shared-links-indexed).

**Source:** [Beyond AI chat leaks: The hidden risk of shared URLs in the age of AI](https://www.linkedin.com/pulse/beyond-ai-chat-leaks-hidden-risk-shared-urls-age-david-konitzny-yrodc/), David Konitzny, LinkedIn, Jul 2026.


# What is a query fan-out (QFO) in AI search?
Source: https://docs.peec.ai/research/what-is-a-query-fanout

A query fan-out is the set of hidden searches an AI engine runs behind one prompt. ChatGPT merges results with Reciprocal Rank Fusion, so content matching multiple fan-outs ranks higher (Peec, 2026).

Query fan-outs (QFOs, also written fanouts or query expansion) are the extra searches an AI engine runs behind the scenes to answer one prompt. Peec's analysis of 5 million fan-outs ([full study](https://peec.ai/blog/patterns-we-see-in-chatgpt-query-fanouts), May 2026) explains the mechanism: a prompt like "best headphones" fans out into hidden sub-queries — best wireless headphones, best noise-cancelling for flights, best budget options, current-year variants — and the engine merges all results into one answer.

Why fan-outs matter for GEO: ChatGPT uses **Reciprocal Rank Fusion (RRF)**, an algorithm that combines scores across the sub-queries. Content that appears across multiple fan-out searches scores higher than content that only surfaces for one — so ranking in AI search means being present across dozens of related queries, not winning one keyword. The structure, length, and number of QFOs directly determine which sources get retrieved and ultimately cited.

Key facts from Peec's 2026 fan-out research, each with its own page:

* ChatGPT injects words like "best", "top", and "reviews" into fan-outs — [Words ChatGPT adds to fan-outs](/research/words-chatgpt-adds-to-fanouts).
* Engines differ hugely in volume: Perplexity 1.4, ChatGPT 2.1, Grok 6.8 fan-outs per prompt — [Fan-outs per prompt by engine](/research/fanouts-per-prompt-by-engine).
* Fan-out queries doubled in length from \~6 to \~12 words between Oct 2025 and Jan 2026 — [ChatGPT fan-out length trend](/research/chatgpt-fanout-length-trend).
* GPT-5.6 made multi-iteration fan-outs the default — [GPT-5.6 retrieval changes](/research/gpt-56-retrieval-changes).

**Source:** [Patterns we see in ChatGPT query fanouts](https://peec.ai/blog/patterns-we-see-in-chatgpt-query-fanouts), Peec (Tomek Rudzki), May 2026.


# What is AEO — Answer Engine Optimization, and how it differs from SEO
Source: https://docs.peec.ai/research/what-is-aeo

A 2026 Stanford GSB paper defines AEO (also GEO, LLMO) as ensuring brands are included and favorably positioned in AI answers; AI-mediated search hit ~30% of search interactions by early 2026.

AEO (Answer Engine Optimization, in the paper "Agentic Engine Optimization") is the discipline of ensuring brands are included and favorably positioned within AI-generated responses. A Stanford GSB paper by Bliey & Chatwin ([SSRN](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=7108218), Jul 2026) frames the field; the terms GEO (Generative Engine Optimization), AEO, GAIO, and LLMO are used largely interchangeably in the industry.

Key arguments from the paper (Jul 2026):

* **AI-mediated search grew from under 10% of search interactions in 2023 to roughly 30% by early 2026** (citing First Page Sage), fragmenting search across general-purpose platforms and specialized assistants.
* **The unit of value is shifting from the click to the synthesis.** In agentic search, inclusion depends less on domain authority or paid placement and more on whether a brand survives retrieval, grounding, and cross-source validation inside LLM systems.
* **The "Perfect Click":** a click arriving from an AI recommendation is confirmatory, not exploratory — the decision is substantially made — so one AI-mediated recommendation can be worth more in conversion terms than hundreds of unqualified impressions.
* **Expected rank across the distribution of users becomes the relevant metric**, not static rank on a common results page, because outputs are non-deterministic and personalized.

The mechanics the paper builds on — passage-level retrieval, query fan-out, reranking — are covered with measured data in [How AI search chooses passages](/research/how-ai-search-chooses-passages) and [What is a query fan-out](/research/what-is-a-query-fanout).

**Source:** [Answer Engine Optimization: How Agentic AI Reshapes SEO](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=7108218), Miles Bliey & Keira Chatwin, Stanford GSB (SSRN), Jul 2026.


# Why listicles get cited by AI search — answer shape, not list bias
Source: https://docs.peec.ai/research/why-listicles-get-cited

Peec's reranker guide (Aug 2026) — listicles win citations because they carry extractable answers, multiple entities, and coverage for many fan-out queries, not a format bias for lists.

Listicles dominate AI citations for a mechanical reason, not a universal "list bias". Peec's reranker guide ([full guide](https://peec.ai/blog/rerankers-for-geo-aeo-how-ai-search-chooses-passages-and-sources), Aug 2026) explains: a good "best AEO tools" listicle names several entities, covers several attributes, answers comparison sub-queries, and contains passages that satisfy multiple fan-out queries at once — and it has the exact answer shape a selection query requests: a shortlist.

Three converging mechanisms from Peec's 2026 research:

* **Fan-out match:** "best" is the word ChatGPT injects most into its hidden searches, and listicles are built around it — see [Words ChatGPT adds to fan-outs](/research/words-chatgpt-adds-to-fanouts).
* **Reranker scoring:** passages containing an extractable direct answer beat merely topical passages by enormous margins — see [Answer shape for AI citations](/research/answer-shape-for-ai-citations).
* **Measured citation rates:** 52% of listicles reach ChatGPT's top citation bucket (Feb 2026 data) — see [Content types cited most by engine](/research/content-types-cited-most-by-engine).

The same logic predicts a definition wins "what is X" and ordered steps win "how to" — the principle is intent-to-answer-shape alignment, not "turn every page into a list". Note the trend caveat: GPT-5.6 (Aug 2026) shifted ChatGPT retrieval share from listicles toward brand product pages — see [GPT-5.6 retrieves product pages over listicles](/research/gpt-56-product-pages-vs-listicles).

**Source:** [Rerankers for GEO/AEO: How AI search chooses passages and sources](https://peec.ai/blog/rerankers-for-geo-aeo-how-ai-search-chooses-passages-and-sources), Peec (Metehan Yesilyurt), Aug 2026.


# Wikipedia in AI search — influences models on two levels
Source: https://docs.peec.ai/research/wikipedia-in-ai-search

Peec's 30M-source analysis (Mar 2026) — Wikipedia is the #4 most-cited domain and shapes AI twice: live retrieval plus core training data, so a pre-cutoff page means the model already knows you.

Wikipedia influences AI answers on two distinct levels, per Peec's 30-million-source analysis ([full study](https://peec.ai/blog/top-domains-cited-by-ai-search-analysis-based-on-30m-sources), Mar 2026), where it ranks as the #4 most-cited domain overall — strong on ChatGPT (its #1 source) and Perplexity, absent from Google's top 5.

* **Live retrieval:** AI engines actively pull from Wikipedia when generating answers.
* **Training data:** Wikipedia is one of the core sources models learn from before release. A brand with a Wikipedia page before the model's knowledge cutoff is not just a citable source — it is something the model already understands.

The catch: Wikipedia has strict notability guidelines, and submissions that fail them get rejected or deleted. Not a quick win, but worth pursuing for brands that qualify.

How training vs retrieval access maps to different crawler bots (GPTBot vs OAI-SearchBot vs ChatGPT-User) is covered in [AI bot types](/research/ai-bot-types). Per-engine source rankings: [Most-cited domains by engine](/research/most-cited-domains-by-engine).

**Source:** [Top domains cited by AI search: Analysis based on 30M sources](https://peec.ai/blog/top-domains-cited-by-ai-search-analysis-based-on-30m-sources), Peec (Tomek Rudzki), Mar 2026.


# Words ChatGPT secretly adds to fan-out searches — best, top, reviews
Source: https://docs.peec.ai/research/words-chatgpt-adds-to-fanouts

Peec's 5M fan-out analysis (Apr 2026) — "best" is the word ChatGPT injects most, in 24.3% of fan-outs for advice questions; "reviews" ranks third, and the current year is added in 5.44% of prompts.

ChatGPT reshapes user questions by injecting words into its hidden fan-out searches. Peec analyzed 5 million query fan-outs collected April 1–21, 2026 ([full study](https://peec.ai/blog/patterns-we-see-in-chatgpt-query-fanouts)); top injected words: **best, top, comparison, reviews, tools, software, features**.

* **"Best" is #1.** For advice-style questions ("Should I use X?", "Do you recommend Y?"), ChatGPT injects "best" into 24.3% of fan-outs — nearly every fourth answer. "Which Samsung Galaxy should I get?" becomes "best Samsung Galaxy phones comparison 2026". This is why listicles built around "10 Best…" match what AI is actually searching — see [Why listicles get cited](/research/why-listicles-get-cited).
* **"Reviews" is #3.** ChatGPT hunts for review content even when the user never asked for reviews. Review sites — including small ones like Sitejabber — directly shape how AI describes brands; see [Review sites in AI search](/research/review-sites-in-ai-search).
* **Current year in 5.44% of prompts** (Grok adds it even more often). Fresh, dated content is more retrievable — updating the pages already cited by AI beats refreshing a whole site.

Content implication: position around "best for \[specific need]", weave in review evidence and ratings, and keep key pages current. Definition and RRF mechanics: [What is a query fan-out](/research/what-is-a-query-fanout).

**Source:** [Patterns we see in ChatGPT query fanouts](https://peec.ai/blog/patterns-we-see-in-chatgpt-query-fanouts), Peec (Tomek Rudzki), May 2026.


# YouTube in AI search — #2 most-cited domain, transcripts included
Source: https://docs.peec.ai/research/youtube-in-ai-search

Peec's 30M-source analysis (Mar 2026) — YouTube is the second most-cited domain in AI answers; AI pulls from video descriptions and auto-generated transcripts, including Shorts.

YouTube is the second most-cited domain in AI search and the dominant video source. Peec's 30-million-source US analysis ([full study](https://peec.ai/blog/top-domains-cited-by-ai-search-analysis-based-on-30m-sources), Mar 2026) found the vast majority of AI-referenced video content comes from YouTube — not just main-channel videos but also Shorts and YouTube Music pages.

Where AI actually pulls the content from: **both the video description and the auto-generated transcription**. The study documents clear cases of Google AI Mode building answers directly from a video description, and separate cases where it pulled from the transcript instead.

The often-missed publishing checklist item that follows: **review the auto-generated transcription before a video goes live** — it is citable source text, not just captions.

YouTube is especially valuable on Google's surfaces: AI Overviews heavily promotes it, making video a pathway into Google's AI answers that ChatGPT does not offer — see [Optimizing for Google AI vs ChatGPT](/research/optimizing-google-ai-vs-chatgpt). Full domain rankings: [Most-cited domains in AI search](/research/most-cited-domains-in-ai-search).

**Source:** [Top domains cited by AI search: Analysis based on 30M sources](https://peec.ai/blog/top-domains-cited-by-ai-search-analysis-based-on-30m-sources), Peec (Tomek Rudzki), Mar 2026.


# Setting up shopping prompts
Source: https://docs.peec.ai/setting-up-shopping-prompts

Build a prompt set for product tracking with strong category coverage as its foundation, then add product-specific prompts where deeper insights are needed.

AI Shopping can only track what your prompts cover. The prompts you choose determine which products, competitors, and buying intents you can analyze.

This guide walks you through how to build an effective prompt set for AI Shopping. It’s designed for brands that sell their own products; multi-brand retailers and marketplaces require a different approach and aren’t covered here.

<Info>
  If you’re new to Peec AI, we recommend starting with [**Setting up your prompts**](https://docs.peec.ai/setting-up-your-prompts) and [**Choosing the right prompts**](https://peec.ai/blog/how-to-choose-the-right-prompts-for-llm-tracking) before continuing with this guide.
</Info>

Two types of prompts are used throughout this guide:

* A **category prompt:** Asks about a type of product, for example, *“What are the best running shoes for beginners?”* It lets you track how all products in that category perform.

* A **product prompt**: Focuses on one specific product, for example, *“Is the Nike Pegasus good for flat feet?”* It gives you a more detailed view of how that individual product performs.

## Step 1: Starting with categories

Every product in your catalog is tracked automatically. Peec AI matches your products to relevant category prompts, so a prompt like *“best running shoes for beginners”* tracks the performance of all the running shoes in your catalog, rather than focusing on a single product.

Categories are the foundation of an effective AI Shopping prompt set for two reasons:

* **Every product is covered:** Products are automatically matched to relevant prompts within their category, regardless of how those prompts are worded.
* **Your data stays organized:** A clear category structure reflects how your product range is organized, making your AI Shopping data easier to analyze.

Use your categories as the structure for your prompt set, then build prompts around the different buying intents you want to track.

<Info>
  You don’t need a prompt for **every** product. Peec AI automatically matches each product to the category prompts it’s relevant to, so a prompt like *“best moisturizers for dry skin”* measures all the moisturizers in your catalog at once.

  This means a well-designed set of category prompts can give you product-level insights across your catalog without creating individual prompts for every product.
</Info>

## Step 2: Build each category's core set

For each category, start with a focused set of prompts that covers the most important shopping decisions. Prioritize **non-branded discovery prompts**, then add a smaller selection of **branded prompts**.

**Non-branded discovery** should make up most of your prompt set. These prompts show whether AI recommends your products when the shopper hasn’t mentioned a specific brand.

* Start with a broad recommendation prompt, such as *“What’s the best \[product category] for \[key use case]?”*
* Add variations for the most important use cases, needs, and buying criteria in that category. Refer to **Step 3**.

**Branded prompts** should make up a smaller portion of your set. They’re useful for understanding how AI responds when shoppers already know your brand, but because your brand is named directly, they’re more likely to include it and can increase your overall visibility. Aim to keep them to around **15–20%** of your prompt set.

<Info>
  Peec automatically classifies these prompts as **Branded**, so you can filter for **Non-branded** at any time to focus on your discovery performance. There’s no need to create a separate project.
</Info>

* *"What are the best alternatives to \[your brand]?"* Captures shoppers who already know you and are comparing options.
* One or two comparisons against your top competitors, phrased as real buying decisions: *"I'm training for my first marathon, should I choose \[your product] or \[competitor product]?"* Comparisons often produce a side-by-side table, which is a good source of attribute data.

**Where product prompts fit:** Add product-specific prompts on top of your category prompts when you want deeper insights into individual products.

* **Small catalogs** (up to about 100 products): Adding roughly three prompts per product can be manageable alongside your category prompts.
* **Hero products:** Prioritize your most important products with prompts around comparisons, buying decisions, and other key purchase considerations.
* **Long-tail products:** Add a smaller selection of prompts for products outside your main priorities. Group them under a single tag so you can track their performance without overwhelming your prompt set.

<Tip>
  **For large catalogs, avoid creating a prompt for every product.** Each product is already matched to relevant category prompts, so individual prompts would mostly duplicate the coverage you already have. Instead, reserve product-specific prompts for your hero products where you want deeper insights.
</Tip>

## Step 3: Think in dimensions

Once the core is in place, expand coverage across three dimensions:

| Dimension | How many | What it looks like |
| :- | :- | :- |
| **Category** | Your top 3 to 5 to start (up to 10 to 30 for large catalogs) | One topic per category, mirroring your catalog's tree. If your catalog is one big category, use product lines (e.g. *"iPhone 17"*, *"Air Jordan 1"*) as the topics instead. |
| **Buyer context** | 2 to 4 per category | The constraint that changes the answer. Keep them within one category so the set stays focused, e.g. for running shoes: *"for beginners"*, *"for flat feet"*, *"for trail running"*, *"under €120"*. |
| **Intent stage** | 2 to 3 per buyer context | How close the shopper is to buying, from weighing options (*"best running shoes for flat feet"*) to ready to purchase (*"where to buy the Nike Pegasus in Germany"*). Peec AI classifies intent automatically; keep the set mostly commercial and transactional. |

To size your prompt set, multiply the main dimensions:

```text theme={null}
coverage = categories × buyer contexts × intent stages
```

Use this as your starting point for building a solid baseline. From there, expand your set by adding distinct buying situations, such as new buyer contexts, use cases, competitor comparisons, markets, or categories.

If you have room to track more prompts, use that capacity to broaden your coverage rather than creating multiple variations of the same question. As long as each prompt represents a genuinely different buying situation, it can add useful signal.

To make this framework work effectively, follow three key rules:

* **Prioritize distinct buying situations:** A new intent, use case, or buyer context adds more value than simply rewording an existing prompt. For your most important prompts, however, tracking a few variations can be useful. Individual prompts can fluctuate from day to day, while several variations can give you a more stable view of performance.
* **Name something shoppable in every prompt**: Include a specific product or product category rather than only describing a general need. For example, *“Best Pilates socks for beginners”* is more likely to trigger shopping results than *“What do I need for my first Pilates class?”*
* **Prompts with commercial intent:** Shopping recommendations appear much more often for commercial prompts than informational ones. Keep some informational prompts where they’re useful, but focus most of your set on product discovery, comparisons, and purchase decisions.

<Info>
  Not every prompt will trigger a shopping recommendation, and that’s expected. Shopping results are more likely to appear for clear, product-focused queries, particularly for physical products rather than services.
</Info>


# Setting up your prompts
Source: https://docs.peec.ai/setting-up-your-prompts

Our in-depth guide to building your prompt and competitor tracking system.

<iframe title="YouTube video player" />

[Watch "Setting up your prompts" on YouTube](https://www.youtube.com/watch?v=T7RnTPSkhDM\&list=PLO3bGBxSo_vU\&index=3)

Prompts are the foundation of everything Peec AI tracks. This section shows you how to create, organize, and manage prompts for meaningful visibility insights.

You'll learn how AI models work, how to write effective prompts, how to organize them with topics and tags, and how to handle prompts at scale using Peec AI's suggestion tools. By the end, you'll have a tracking system that captures your visibility across AI platforms.

## How prompts work

Understanding how prompts work with AI models is essential for effective visibility tracking. This section covers how AI models interpret your questions and what that means for your tracking strategy.

### The difference between prompts and keywords

Traditional SEO focuses on keywords. AI search requires understanding how people actually converse with AI models.

* **Keyword approach:** “Best CRM software.”
* **Prompt approach:** “What CRM would work best for a sales team of 10 people?”

Key differences:

* Prompts are longer and conversational.
* Prompts include context and constraints, not just topics.
* Prompts use natural language patterns.

Understanding these fundamentals helps you create effective prompts that capture genuine user conversations with AI models.

### How AI models process prompts

AI models like ChatGPT, Claude, and Perplexity don’t match keywords like traditional search engines. They analyze the entire prompt to understand three key things:

* **Intent recognition:** What you’re actually asking for. Examples of clear intent are:
  * “What’s the best…” (seeking recommendations)
  * “How do I…” (seeking instructions)
  * “Compare…” (seeking analysis)
* **Context analysis:** The specific situation or constraints mentioned. Context provides constraints and situation details that shape how the AI fulfills the intent. Types of context are:
  * **Audience:** “for small businesses,” “for beginners”
  * **Use case:** “for remote teams,” “for e-commerce”
  * **Constraints:** “under \$100,” “with less than 50 employees”
* **Response generation:** Crafting an answer that matches both intent and context.

Different intents can lead to different responses, while prompts with the same intent tend to produce similar results even when they’re phrased differently.

For example:

* “What are the best running shoes for beginners?” vs. “What are the best running shoes for marathon training?” → Different buying needs → Different recommendations.
* “What are the best running shoes for beginners?” vs. “Which running shoes are best for someone new to running?” → Same buying need, different wording → Similar recommendations.

This means you don’t need multiple variations of the same question. AI models recognize similar intents regardless of exact phrasing.

<Info>
  **Prompt example:** “What’s the best project management tool for creative agencies with remote teams under 20 people?”

  * **Intent:** “What’s the best project management tool...” (the main ask).
  * **Context:** “...for creative agencies with remote teams under 20 people” (the specifics).
</Info>

What this means for your tracking:

* **Exact phrasing doesn’t matter much.** Semantically similar prompts will lead to very similar results over time. Focus on capturing the right intent and context rather than perfecting every word.
* **Informational prompts need brand context.** For prompts seeking instructions (“How do I…”), AI models likely won’t mention brands unless you specifically ask for them. Add context, such as “what tools should I use?” or “which platforms work best?” to get brand mentions in your tracking.

### Intent types

Peec AI automatically tags every prompt with one of three intents, based on where the buyer is in their journey. Intent is one of the most useful filters for reading Visibility and Share of Voice, and it drives the intent mix in Prompt discovery.

* **Informational:** The person wants to learn or get instructions, not compare or buy. Example: "How do I improve email open rates for B2B clients?" AI often answers these without naming brands, so they surface fewer brand mentions unless you add brand context.
* **Commercial:** The person is comparing or researching options before a decision. Example: "What's the best CRM for marketing agencies under 50 people?" These reliably surface brands and are the core of most tracking.
* **Transactional:** The person is ready to act, buy, or take a specific step, often naming a product or price. Example: "HubSpot pricing for a 10-person team."

## Prepare your topics

Think in clusters of related prompts rather than individual questions, for better suggestions and organization.

Before creating individual prompts, organize your tracking around topics. Topics help you think systematically about the different areas where you want visibility, and they unlock better prompt suggestions. When you create topics first, Peec AI can generate more targeted suggestions based on those specific themes, tailored to your focus areas rather than generic.

### How topics work

Topics create folder-like structures where each prompt belongs to exactly one topic. Think of them as containers for related prompts around specific themes or product areas.

Examples of effective topics:

* **Marketing Analytics:** Prompts comparing tracking tools, attribution models, and reporting platforms.
* **AI Writing:** Prompts about content generation, editing assistance, and writing workflows.
* **Remote Collaboration:** Prompts comparing video conferencing, project management, and team communication tools.
* **Security:** Prompts comparing fraud protection, security features, and safety measures across financial services.

### Setting up your first topics

<img alt="Addnewtopic" />

Start with 3 to 5 broad areas where you want to track AI visibility:

1. **Identify your key product areas:** What are the main categories where you want to appear?
2. **Create topics for each area:** Use clear, specific names that reflect those categories.
3. **Request topic-based suggestions:** Generate prompts tailored to each topic area.
4. **Expand with manual prompts:** Add specific prompts that suggestions might miss.

You can create more topics later, but starting with topic-based thinking helps you build a more organized prompt strategy from day one. Topics also make analysis easier: you can track visibility at the topic level instead of prompt by prompt.

## Create your prompts

There are four ways to add prompts, from fully manual to fully guided. Go to **All Prompts** in your sidebar to get started.

* Add prompts manually
* Bulk CSV upload
* Prompt suggestions
* Prompt discovery

### Option 1: Add prompts manually

<img alt="Addintpromptsmanually" />

Add prompts individually or in batches.

* Click **Add prompt** in the top right of the All Prompts page.
* Enter one prompt, or several using line breaks (one prompt per line).
* Set **Location** to choose which country the prompt runs from.
* Add a **Topic** and **Tags** (optional).
* Click **Add** to save.

Read more about [creating topics and tagging prompts](https://docs.peec.ai/organizing-your-setup#add-your-tags-and-topics).

<Info>
  The Location setting determines the geographic location where your prompt runs. Different locations can produce different AI responses based on regional content preferences and availability.

  If your desired country isn’t available, contact us, and we’ll add it in the next update.
</Info>

### Option 2: Bulk CSV upload

<img alt="Image" />

Upload many prompts at once with a structured CSV file.

* Click **Add prompt** and select **Bulk upload**.
* Drag and drop your CSV file, or click to browse.
* Confirm the preview matches your intended structure.
* Imported prompts appear in the **Active** tab and start running immediately.

Your CSV file should be comma- or semicolon-separated, with this structure:

* **Row 1:** Header row (ignored during import).
* **Column 1:** Prompt text (one per row, max 200 characters per prompt).
* **Column 2:** Location, using [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (US, DE, and so on). If blank or invalid, your project's default location is used.
* **Column 3:** A topic (for example, CRM Software).
* **Column 4 and beyond:** Tags to assign to each prompt. Add text to assign as many tags as you need, using one column per tag.

<Info>
  You can [download this example CSV file](https://app.peec.ai/Peec%20CSV%20Template.csv) or this [Google Sheets template](https://docs.google.com/spreadsheets/d/1VgBaBqAesMpDoRtGc_zAntDtUEE8ZjXxdM3ME3-PAYo/edit?usp=sharing) to get started. Make sure your CSV file is UTF-8 encoded.
</Info>

### Option 3: Prompt suggestions

<img alt="Promptsuggestions" />

Peec AI's suggestion engine creates prompts based on your website, industry context, and existing topics.

* Go to the **Suggested** tab in the Prompts section and review the suggestions.
* Click **Track** to move a prompt to your **Active** tab.
* If you don't see suggestions, click **Suggest more** to create new ones.

<Info>
  Click **Suggest more** to generate additional suggestions. If you've reached the limit of suggested prompts, reject a few unsuitable ones and click again. Accepted prompts join your Active prompts and start running immediately, on the regular 24-hour cycle.
</Info>

### Option 4: Prompt discovery

<img alt="Cleaned8" />

The setup takes four steps:

* **Profile:** Describe what you sell and who buys it, including your products or services and buyer personas. You can also add up to 200 characters of additional context to further guide the suggestions Peec generates.
* **Markets:** Pick the locations and languages you want to track your brand's performance in. Prompts are generated per market.
* **Topics:** Review the suggested topics before any prompts are generated. Rename or delete the ones that don't fit, and add your own for anything the suggestions missed.
* **Distribution:** Set the share of branded versus unbranded prompts and the intent mix (informational, commercial, transactional). Each set has to add up to 100%. The defaults, 20% branded and a 25/50/25 intent split, match what works for most brands.

### Reviewing suggestions

Generated prompts land on the results page. The left sidebar lists your topics; selecting one shows its prompts in the table. You can regroup the sidebar by branding, intent, persona, market, or language to check coverage from a different angle.

* Accept or reject prompts individually, or use **Activate all** per group.
* Accepted prompts become active prompts and join the regular daily run.
* Use **Generate more prompts** to top up suggestions, or **Modify setup** to change your profile, markets, or distribution at any time.

<Info>
  Accepted prompts count toward your plan's prompt limit, so review before activating in bulk.
</Info>

### Checking coverage

The coverage overview compares what you've accepted against the distribution you asked for, so you can see what a generated set is missing before you commit to it. Open it from the results page. Each topic, country, and persona shows where it stands:

* **On target:** It matches the distribution you set.
* **Not started:** Nothing is accepted yet.
* **Empty:** The topic has no prompts at all.

<Info>
  **Generate more prompts** adds more prompt suggestions directly from the overview to expand coverage for a specific market or buyer persona without leaving the page.
</Info>

### Suggested vs. Active topics

When the sidebar is grouped by topic, your topics split into two sections:

* **Suggested:** Topics you haven't started reviewing yet. Every topic begins here after generation, with a full set of suggestions and no active prompts.
* **Active:** Topics where you've accepted at least one prompt. A topic moves here automatically the first time you accept a suggestion from it, and it keeps any suggestions you haven't reviewed yet.

On a fresh run, every topic sits under Suggested and the Active section is empty. That's expected, not a missing state. As you work through the suggestions, topics move into Active. Hover over any topic to see its exact counts: how many prompts are already active and how many suggestions are still waiting for review.

<Info>
  A topic with nothing left to review (everything accepted or rejected) shows **No suggested prompts** on hover and stays under Active with its accepted prompts.
</Info>

## Use prompt volume

<iframe title="YouTube video player" />

[Watch "Prompt Volume" on YouTube](https://youtu.be/wjQqCz1ku_o)

Prompt Volume shows you exactly what people are searching for in your industry and how much demand exists for topics related to your brand. It’s a powerful feature that analyzes your prompts and assigns them a relative demand score from 1 to 5. By using this metric, you can focus your content strategy on what truly resonates with your audience.

<Info>
  Prompt Volume helps you find high-impact topics by measuring genuine search interest, ensuring your content meets a real need.
</Info>

### How prompt volume works

Prompt Volume uses a multi-layered model and process that involves multiple steps. Among them:

* **Real-time search trends:** Finding questions/queries people actually search for on web engines such as Google, relevant to the business.
* **Keyword weighting:** Highly relevant and business-specific queries are given higher importance.
* **Relative to the industry scores:** Volume is calculated relative to your own keyword landscape, not a global average.

The model identifies the core themes in your prompts, then matches them to what people are already searching for. The result is an industry-relative score that shows the demand for your content.

### Understanding your scores

Prompt Volume scores range from 1 to 5, indicating how much search interest exists for your prompt’s topics relative to your industry:

**Score 1** - Very low search volume relative to your industry.

**Score 2** - Low search volume relative to your industry.

**Score 3** - Moderate search volume relative to your industry.

**Score 4** - High search volume relative to your industry.

**Score 5** - Very high search volume relative to your industry.

## Manage prompt limits

Your plan includes a specific number of active prompts. You can see it at the top of the **All Prompts** page.

Here’s how the limits work:

* **Active prompts:** Count toward your plan limit and run daily.
* **Archived prompts:** Don’t count toward limits but preserve historical data. You can always activate them from your **Archived** tab.
* **Deleted prompts** (not visible): Don’t count toward limits and erase all historical data. If they were deleted by accident, we might be able to recover them for you.
* **Suggested prompts:** Don’t count until you accept them.

This system lets you experiment with new prompts while staying within your plan by archiving less important ones rather than deleting them entirely.

<Info>
  Depending on your subscription plan, there is a limit to the number of **countries** you can track. This limit applies **per project** and only affects the **prompt locations** you can configure.

  You can find the country limits and a full breakdown of each plan here: [Country Limit](https://peec.ai/pricing).
</Info>


# Sidebar navigation 
Source: https://docs.peec.ai/sidebar-navigation

A quick guide to the sections available in the Peec AI sidebar, their key features, and what you can do in each one.

## General

* **Collapse a group:** Click a group name to hide its pages and keep the sidebar tidy.
* **Jump to any page:** Click the search icon next to your project name, or press **⌘K** (**Ctrl+K** on Windows). Search for pages, prompts, domains, URLs, and projects all from one place.
* **Open Settings:** Click **Settings** at the bottom of the sidebar to access your project and company settings. Click **Overview** at the top to return to the main navigation.
* **Switch your workspace:** The dropdown at the top of the sidebar moves you between projects.
* **Browse and Chat:** Use the tabs at the top of the sidebar to switch between the platform and the in-app AI agent.

## Home

* **Overview:** Your main dashboard, giving you a high-level view of your AI performance, including visibility trends, tracked brands, top sources, and recent AI responses. Use the timeframe, model, and topic filters to focus on specific data. See [**Understanding your performance**](/understanding-your-performance).

## Brand

* **Insights:**  Understand your brand performance in detail. For which topics, AI models, do you dominate, and for which ones are you losing against your competitors? See [**Brand insights**](/brand-insights)
* **Perception:** See how AI describes your brand and how you compare to competitors on the attributes that matter most to buyers. This is an objective view, independent of your tracked prompts. See [**Perception**](/brand-perception-market).

## Prompts

* **All prompts:** Create and manage the prompts you want to track. Organize them with topics and tags, then monitor how they perform over time. See [**Setting up your prompts**](/setting-up-your-prompts).
* **Discovery:** Generate a complete set of prompts for your brand using our built-in tool, then review and edit them before adding them to your project.

## Sources

* **Gap analysis:** Quickly identify the domains and URLs where your competitors are being mentioned, but your brand is not.
* **Domains**: View data by domains (UGC, Editorial, Corporate, Reference, etc.) and understand which websites AI models believe to be authoritative.
* **URLs**: View more granular data by URLs (Article, Comparison, Listicle, How-to guide, Product page, etc.), find which pages are being cited, and identify optimization opportunities through the gap analysis.

## Optimize

Prioritized actions to improve your AI visibility, split between site fixes, your own content, and third-party sources. Visible to company and project owners.

* **Actions:** A ranked list of improvements to make, with the evidence behind each one. See [**Actions**](/actions).
* **Impact:** Measure how your visibility changed after implementing a recommendation.

## Results

* **Ranking:** See where your brand ranks compared to other tracked brands for a prompt.
* **Chats:** The individual AI responses your metrics are built from. Read these when a number surprises you. See [Understanding chats](/understanding-chats).
* **Fanouts:** The background searches a model runs while it answers a tracked prompt. You see which queries it generates, how often each one comes up, and whether you appear in them.
* **Ads:** Track the sponsored placements appearing in your ChatGPT prompts, including who's advertising and where the ads direct users. See [Ads](/ads).

## Agent analytics

How AI agents reach and read your site.

* **Crawl Insights:** See which AI agents visit your website, the pages they access, and how their activity changes over time. Requires a connected server log provider or uploaded log file. See [**Crawl insights**](/crawl-insights) and [**Connecting your data**](/connecting-your-data).
* **Crawlability:** Check which AI agents are allowed or blocked by a tracked domain's **robots.txt** file. No setup or server log connection is required. See [**Crawlability**](/crawlability).
* **AI Referrals:** See how much traffic AI platforms send to your website and how those visitors behave, using data from Google Analytics.

## Shopping

* **Overview:** Understand how your products are performing against those from your competitors. Get an overall view of who is winning and which ones your competitors are winning. You can connect with Shopify or upload a CSV file of your catalog.
* **Products:** See each product in your catalog in more detail, including where they stand in terms of visibility, win rate, and position. Analyze the queries that are triggering those results and compare them with your competitors'.

<Info>
  To see this tab, you first need to set up your catalog in the overview tab, or simply select the option of "continue without uploading".
</Info>

## Settings

The **Settings** button at the bottom of the sidebar gives you access to your project and company settings.

### Project settings

* **Profile:** Help Peec understand what your brand is all about. Set the industry, the attributes, and markets in which the brand operates to receive even better prompts suggestions.
* **Facts:** Claims AI makes about you are checked against the facts you write here. One statement per line.
* **Brands:** Set up and manage competitor tracking. Add brands manually or accept suggestions, configure detection rules with RegEx, and customize display settings.
* **Tags:** Create labels to organize and filter your prompts. Use tags to group related prompts and analyze performance across different themes or campaigns. For example, tag prompts with "product comparison," "pricing," or "customer support" to track performance by topic area.

### Company

* **Settings**: Edit your company settings, such as the name and domain.
* **Projects:** Configure project-specific settings, including project name, domain, location, number of prompts per project, and which AI models you're tracking. Export an archive of all chat messages as CSV.
* **API Keys:** Get access to powerful [API features](https://docs.peec.ai/api/introduction) by creating your API key for custom integrations (Available for the Enterprise plan only).
* **Connected Apps:** The third-party tools you've granted access to, and where to revoke them.
* **Members:** Manage and invite team members at the company or project level. Control access and permissions for different users within your project.
* **Billing:** Update or cancel your plan subscription and manage payment methods.

## Your account

Your name at the bottom of the sidebar opens the account menu, there you will find:

* **Refer & Earn:** Share your personal referral link via email, LinkedIn, WhatsApp, or Slack and earn up to **\$1,000 in commission**, while your referrals get **30% off their first month**. Track your referrals and earnings directly from the page.
* **Theme:** Light, dark, or match your system.
* **Logout:** Sign out of Peec AI.

## Need Help?

Get support when you need it:

* Browse our [Product Docs](https://docs.peec.ai/) for comprehensive guides.
* Check the [Help Center](https://help.peec.ai/en/) for quick answers.
* Or [get help directly from our support team](mailto:support@peec.ai) for personalized assistance.


# Single sign-on (SSO)
Source: https://docs.peec.ai/sso

Sign in to Peec AI through your company's identity provider, and require it for everyone on your domains.

Your team can sign in to Peec AI with the same identity provider (IdP) it already uses, instead of keeping a separate Peec login. Once a connection is in place, you can also require it, so only people who authenticated through your IdP can reach your projects.

<Info>
  SSO connections are set up by the Peec AI team. To get started, contact [support@peec.ai](mailto:support@peec.ai).
</Info>

## Signing in with SSO

1. Go to [app.peec.ai](https://app.peec.ai) and select **Sign in with SSO**.
2. Enter your work email address. Peec matches its domain to your company's connection.
3. Finish signing in with your identity provider in the window that opens.

The first time you sign in, your account is created and added to your company. A project owner still needs to add you to a project before you see any data.

<Tip>
  Peec has a dedicated sign-in page for each connection, so your team can bookmark one URL instead of entering an email address every time. Ask for yours during setup.
</Tip>

## Supported protocol

Peec supports **SAML 2.0** (Security Assertion Markup Language), and no other SSO protocol. Any SAML 2.0-compliant identity provider works.

* **OpenID Connect (OIDC)** isn't offered for enterprise sign-in.
* **SCIM** (System for Cross-domain Identity Management) directory provisioning isn't offered. Accounts are created the first time someone signs in through your IdP.

<Note>
  Signing in with a personal Google or Microsoft account is social login, not SAML SSO. Those are separate sign-in methods, and your SSO connection doesn't cover them unless you block them.
</Note>

## Setting up a connection

1. **Peec registers your identity provider.** You share your IdP's SAML metadata, and Peec gives you the values to configure on your side.
2. **You verify each email domain.** Add a TXT record at `_peec.<domain>` with the value Peec gives you, in the form `domain-verification=<code>`. Every domain on the connection has to verify before the connection can be switched on.
3. **Your team signs in.** Anyone with an email address on a verified domain is routed to your IdP.

One connection can cover several email domains. Each of them needs its own record.

## Requiring SSO

Two separate controls set how strictly SSO applies. Ask the Peec AI team for either or both.

* **Block other login methods**: Applies to the domains on a connection. Password and other sign-in options stop working for those addresses. Everyone on them goes through your IdP.
* **Require SSO sessions**: Applies to your whole company. Only sessions that signed in through one of your enabled connections reach your projects, including in the app, the MCP server, and Data Studio. Customer API keys aren't affected.

Either change takes up to five minutes to apply.

<Info>
  You can't lock your own company out. Requiring SSO sessions needs at least one enabled connection, and the last enabled connection can't be switched off while the requirement is on.
</Info>

## Requirements

* A SAML 2.0 identity provider.
* Access to the DNS records of every email domain the connection covers.


# Understanding chats
Source: https://docs.peec.ai/understanding-chats

Learn how to read the AI responses that form the foundation of all your analytics.

<iframe title="YouTube video player" />

[Watch "Understanding chats" on YouTube](https://youtu.be/EnxfmarTlrg)

Chats are the AI-generated responses Peec AI produces by running your prompts daily across different platforms. Understanding a chat's anatomy matters, because these responses are the basis for all dashboard metrics, source data, and competitive analysis. Every visibility score, position ranking, and source classification starts with an analysis of these individual conversations.

## Anatomy of a chat

<img alt="Image" />

You’ll find recent chats on your **Overview** dashboard, but you can view the last 100 chats for each prompt by clicking on the individual prompt.

Each chat contains specific elements that Peec AI analyzes to generate your metrics and insights:

* **Created:** Whether the prompt ran successfully.
* **Model:** Which AI platform generated the response (ChatGPT, Claude, Gemini, and so on).
* **Location:** The geographic location Peec AI prompted from (for example, United States).
* **Sentiment:** How the AI model talks about your brand, positively, neutrally, or negatively (a score between 0 and 100).

Each chat response contains:

* **Main response:** The actual AI-generated answer to your prompt.
* **Brands mentioned:** Shows which brands (including yours) were mentioned and where in the response.
* **Query fanouts:** Shows the query fanouts performed by the model when generating the answer for a specific prompt.
* **Sources sidebar:** All URLs the AI model referenced or cited when creating the response.
* **Links:** Pages the answer linked to in its own text, listed in the sidebar under **Links**.

## Sources vs citations

Not all sources are citations, but every citation is a source. Understanding this distinction helps you interpret your data correctly.

* **Citations:** Sources explicitly referenced within the AI response text. They appear as in-line mentions in the response body, indicating the AI used specific information from that URL for particular sentences or sections.
* **Sources:** All URLs the AI model accessed while generating the response. This includes citations plus additional sources the AI considered but didn't explicitly reference. Sources appear in the sidebar, and often at the bottom of a chat, even when not directly cited.

For example, an AI response might cite 5 sources directly in the text but show 8 in the sidebar. All 8 contributed to the response, but only 5 were explicitly referenced. When a URL is cited multiple times, it appears only once in the sidebar.

Citations drive traffic to your website, while sources without citations still build your authority and influence the AI's understanding. Both contribute to your AI visibility, but they call for different optimization strategies, so track both to get the complete picture of your performance.

## Links

<img alt="Cleaned14" />

AI answers don't just cite sources. They can also include links directly in their responses. Peec AI tracks these as **Links**, helping you see which websites AI directs users to, rather than which sources it uses to generate its answers.

* **In the answer:** Links appear as underlined text within the AI response. Hover over a link to see its domain. Links to your website are highlighted with a green underline and a **You** badge.
* **In the sidebar:** The **Links** section shows each link's text, URL, and the number of times it appears in the answer. If a chat contains no links, this section won't appear.

<Info>
  If a page is already listed as a source, Peec AI won't count it again as a link. This means a URL can only be classified as either a **source** or a **link** within the same chat. Links to the AI platform's own pages are also excluded.

  Since some AI platforms include links in their answers more frequently than others, it's best to compare link data within the same platform rather than across different platforms.
</Info>

## How AI platforms behave

Different AI models handle sources and citations differently, which affects your data patterns:

* **ChatGPT:** Sometimes performs web searches and sometimes doesn't. When it doesn't search the web, you'll see responses with no sources listed. This is normal model behaviour, not a data issue.

* **Claude and other models:** Each has unique patterns for how they search, cite, and reference sources.

<Tip>
  AI models have inherent randomness in source selection: a source might appear one day and be absent the next. Focus on trends over weeks rather than daily changes.
</Tip>

## Reading chat position rankings

When multiple brands appear in a chat, Peec AI calculates position based on mention order, including all detected brands, not just your tracked competitors.

For example, if a chat mentions Hyundai (1st), Chevrolet (2nd), and BMW (3rd), BMW ranks in position 3. If tomorrow's chat mentions Hyundai, Chevrolet, Ferrari, and BMW, then even though you haven't added Ferrari as a competitor, BMW's position becomes 4th.

A stronger position (closer to 1) indicates that AI models consider your brand to be:

* The most authoritative source for the topic.
* The go-to reference in your industry.
* Highly relevant to the user's query.

This gives you competitive context by showing where you rank among all the mentioned brands, not just your selected competitors.

<Info>
  Review chats regularly to understand how AI models reference your brand and competitors. This helps you spot patterns, discover new competitor names to track, and identify sources worth targeting for outreach.<br /><br />You can also export all chats generated on your account so far via the **Project** tab. You can use this export to further analyze the responses and make your own report.
</Info>

## Chat features

Chat features are structured flags attached to every chat, showing you at a glance what type of content an AI model included in its response: whether a chat contains ads, maps, shopping results, or a live web search.

Every time Peec AI runs a prompt, the AI model's response can contain more than text. It might serve a sponsored ad, pull up a local business map, or run a live web search before answering. These extras are called **features**, and they matter because they tell you what kind of result your prompt is actually triggering.

For example, a prompt-driven ad placement means your topic is already being monetized by AI. A prompt that pulls up maps means the AI is treating it as a local discovery query.

### Available features

Each chat can carry any combination of these features:

* **Ads:** The AI model included a sponsored placement. Useful for understanding monetization pressure on your topics.
* **Maps:** The AI returned a local business map result. Common for location-based queries.
* **Web search:** The AI performed a live web search to generate the response, rather than answering from its own training data.
* **Shopping:** The AI included product or shopping results
* **Product comparison:** Chats in which the AI makes comparisons between two or more brands
* **Links:** The answer linked to a page in its own text. See [Links](#links).

### Where to find features

Features appear in two places:

* **All chats table:** Each chat row displays its features as visual flags, and the **Links** column shows the domains the answer linked to. Use the dropdown filter at the top of the table to show only chats matching specific feature types (for example, only chats that included ads, or only chats where web search was used).
* **Prompts and Topics tables**: Each prompt and topic shows aggregated feature percentages. For example, you might see that 42% of chats for a given prompt included ads, or that 80% triggered a web search. This helps you quickly identify which prompts drive which response types without opening individual chats. The **Links** column on the Prompts table also shows each prompt's top linked domains.

<img alt="Chatfeature" />

### Filtering by features

In the All Chats table, click **Filter**, then select any feature to narrow the list. A few ways to use this:

* Filter to **Ads** to see every response where your brand appeared alongside paid placements.
* Filter to **Maps** to identify which prompts are driving local discovery results.
* Filter to **Web search** to focus on chats where the AI actively looked things up; these tend to have more recent, source-driven content.
* Combine multiple filters to find chats with overlapping features, such as shopping and web search.

<Info>
  All chat features, ads, maps, shopping, web search, and feature flags are available through the Peec API and MCP. You can filter by feature type the same way you filter by model, country, or date range.
</Info>


# Understanding sources
Source: https://docs.peec.ai/understanding-sources

Discover which websites AI models trust and learn how to optimize your presence across them.

<iframe title="YouTube video player" />

[Watch "How to understand your sources" on YouTube](https://www.youtube.com/watch?v=3i3vHMjxZAg\&list=PLO3bGBxSo_vU\&index=5)

Sources are the foundation of AI optimization. While you can’t directly control AI-generated responses or the data models are trained on, you can influence the sources they rely on when generating answers. Understanding which websites and pages AI models use helps you identify the sources strengthening your brand’s authority, where competitors are gaining visibility, and where opportunities exist to improve your own presence.

## Why sources matter

Sources play an important role in your AI visibility. They are the URLs AI models access while generating a response, while **citations** are the sources explicitly referenced in the final answer. Both can influence what AI says and which brands it recommends.

You have direct control over the content on your own website, and you can influence external sources through PR, partnerships, community engagement, and social channels. Building a stronger presence across the sources AI relies on can increase your visibility in AI responses.

<Info>
  **Important limitation:** AI models only see HTML content. They can’t read behind paywalls or load JavaScript-dependent content.
</Info>

Under **Sources**, you'll find the **Domains** and **URLs** pages. Use both to understand the types of content AI models rely on when answering your tracked prompts. These insights help you reverse-engineer what's working for competitors and other domains, identify content opportunities, and find websites where partnerships or collaborations could increase your visibility.

## Gap analysis

You can access **Gap Analysis** directly from the sidebar or use it within the **Domains** and **URLs** pages. It highlights sources where your competitors appear, but your brand does not, helping you uncover content gaps and potential partnership opportunities you might otherwise miss.

Use these insights to understand where competitors are gaining visibility and identify opportunities to strengthen your own content strategy.

How to prioritize opportunities:

* **Start with high Gap Scores:** Focus on sources that are frequently used by AI and where multiple competitors already appear.
* **Review URL details:** Click any URL to see how AI models have used that page over time, including which prompts consistently retrieve and cite it.
* **Choose your approach based on the source type:** Editorial sites may be better suited for PR or partnership outreach, while UGC platforms may offer opportunities for direct community engagement.

## How to use source insights

Different source types call for different optimization approaches. Use your source data and **Gap analysis** to see where your brand is missing, and prioritize the opportunities worth focusing on.

A few strategies by source type:

* **Editorial:** Focus on digital PR and journalist outreach.
* **Corporate:** Explore partnerships and directory listings.
* **UGC:** Engage authentically in relevant communities, collaborate with creators, or identify channels worth reaching out to.
* **Reference:** Update incomplete or inaccurate information through the appropriate channels.
* **Your own website:** Optimize your content structure and make sure your pages are accessible and easy for AI to understand.

For URLs, you can also see which types of pages are cited, such as **Articles**, **Listicles**, **How-to Guides**, and **Comparisons**. Use this to understand which content formats perform well in your industry, and where you may want to adjust your own content strategy.

### Understand social sources in more detail

Social platforms such as **YouTube, Reddit, LinkedIn, TikTok, Medium, and Instagram** can play an important role in AI Search. Peec AI gives you additional information under **Sources** to help you understand how your own and competitors’ social channels are performing, as well as identify third-party channels you may want to collaborate with.

You can find social channel information in:

* **URLs & Domain detail pages:** See **Channel movers** and channel tags next to relevant page titles in the URLs table.
* **URL detail page:** See the associated **Channel** highlighted in the KPI row.

<img alt="Channelmovers" />

<Info>
  If you’ve [defined your own and competitors’ channels](https://docs.peec.ai/quickstart-guide) under **Brands**, you can also filter the URLs table by **You, Competitor, Other,** and **No channels** to quickly compare where social citations are coming from.
</Info>


# Understanding your performance
Source: https://docs.peec.ai/understanding-your-performance

Your main analytics hub for understanding how your brand performs across AI models, prompts, and competitors.

<iframe title="YouTube video player" />

[Watch "How to read your overview in Peec AI" on YouTube](https://www.youtube.com/watch?v=o9vAYU5gfic\&list=PLO3bGBxSo_vU\&index=4)

Your **Overview** dashboard shows key areas of your AI search performance, in addition to all recent chats generated for your prompt set. Use the filters at the top to focus your analysis.

Here you'll see:

* **Visibility graph:** See where you stand against competitors across all your prompts, with daily fluctuations.
* **Brands:** Your average visibility, sentiment, and position compared with top competitors.
* **Top sources:** See which websites and domains AI platforms use most when answering your prompts, along with a breakdown of the source types they rely on, such as **Corporate, Editorial, UGC,** and more.
* **Recent chats:** See the latest AI responses across all your tracked prompts. By default, all recent responses are shown, but you can toggle the view to see which brands were mentioned alongside yours.

<Tip>
  Click any competitor, domain, or chat to dive deeper.
</Tip>

## Dashboard filters

Use the filters at the top of your dashboard to narrow down your data and focus your analysis on what matters most.

* **Competitor**: Filter by a competitor to see their visibility and which sources AI uses when answering about them.
* **Date range:** View data for different time periods (default is the last 7 days). Select a predefined range or a custom span. Change indicators to compare performance with the previous span of the same length.
* **Tags:** Filter by prompt tags using **AND/OR** logic. Select multiple tags to control which prompts are included:
  * **AND:** Shows only prompts that have **all** the selected tags.
  * **OR:** Shows prompts that have **at least one** of the selected tags.
* **Models:** Focus on specific AI platforms (ChatGPT, Claude, Gemini). Use this to see how you perform on individual models versus the average.
* **Country:** Filter by geographic location where prompts were run from (based on your prompt setup).
* **Topics:** Filter by specific topic folders to focus your analysis on particular prompt groups.

<Info>
  Tag filters don't apply to the recent **All Chats** section; you'll always see the recent chats regardless of tag selections.
</Info>

<Info>
  The **Country** filter becomes available once you have prompts that are assigned to different countries.

  The **Tag** and **Topic** filters become available once you've assigned tags or topics to your prompts.
</Info>

## Main Overview

### Visibility graph

The visibility graph shows your brand and your top 6 competitors, and how their visibility changes daily. This gives you a clear picture of competitive dynamics and helps you identify who's gaining or losing ground in AI responses.

Each line represents a brand’s **Visibility %** over your selected time period. Hover over a line to see the exact percentage and which brand or competitor it represents.

### Brands

This section shows the same 7 brands from the visibility graph, with their average performance over your selected timespan:

* **Visibility:** Percentage of AI responses where your brand appears. Shows how frequently AI models mention your brand when answering relevant prompts. Higher visibility percentage means better brand awareness in AI search.
* **Share of Voice (SoV):** Percentage of your brand mentions in AI responses compared to all tracked brands mentioned. A high SoV means that you’re more likely to be the main focus of conversation in chats than competitors.
* **Sentiment:** How positively AI platforms describe your brand (0 to 100 scale), based on the language and context around your mentions (from words like "trusted," "reliable," and "leading" to critical or negative associations). Higher scores mean more positive perception.
* **Position:** Your brand’s average ranking when it appears in AI responses. It shows where your brand ranks against all other brands mentioned, including both tracked and untracked competitors. Lower numbers are better: **Position 1** means your brand is mentioned first, **Position 5** means fifth, and so on.

<Info>
  Read more about identifying and adding competitor brands [here](https://docs.peec.ai/identifying-your-competitors).
</Info>

<Tip>
  Click **Show All** to view the complete ranking with all competitors you've set up.
</Tip>

### Top sources

The **Top Sources** section shows which websites AI platforms reference most when answering your prompts, split by **Source Type** and **Domain**:

* **Source type chart:** Shows the number of retrievals by domain category (Editorial, Corporate, UGC, etc.). This helps you understand what types of sources dominate in your industry.
* **Top domains table:** Lists the 8 most-used domains with their metrics:
  * **Retrieved:** Percentage of chats where at least one URL from this domain was used as a source.
  * **Retrieval rate:** Average number of times a URL from this domain was used as a source per chat.
  * **Citation rate:** Average number of times the domain was explicitly cited when used as a source.
  * **Type:** Domain category classification.

<Info>
  To learn more in-depth about **Sources**, head over to this section.
</Info>

<Tip>
  Click **All domains** to access the complete **Sources** section for more detailed analysis.
</Tip>

### Links

The **Links** section shows the websites and pages AI answers link to in their own text, separate from the sources they cite. See [Links](/understanding-chats#links) for how a link differs from a source.

* **Linked domains:** Domains ranked by the number of chats that link to them.
* **Linked URLs:** The individual pages, ranked the same way.

Both cards have four tabs:

* **Top:** The domains or pages the most chats linked to in the selected period.
* **New:** Domains or pages linked to for the first time in the selected period.
* **Trending:** The largest rise in chats linking to them.
* **Losing:** The largest drop in chats linking to them.

<Tip>
  Hover over a row to see its share of chats. Click a row to open the linked website or page.
</Tip>

### All chats

These are the chats Peec AI creates by running your prompts daily against the AI models. By default, you'll see all recent chats; you can use the filters at the top to filter by brand, features, and sources.

If your visibility is zero for certain prompts, you can still see that the prompts are running and what the AI models are saying about your topic area.

Each chat shows the prompt that generated it, followed by these columns:

* **Mentions:** The tracked brands mentioned in the answer.
* **Sources:** The domains the AI used as sources.
* **Links:** The first three domains the answer linked to. Hover to see every linked domain and how many links went to each.
* **Features:** The [chat features](/understanding-chats#chat-features) in the answer, such as ads or a web search.
* **Citations:** How many times the answer cited its sources.
* **Position:** Your brand's position, if it's mentioned.
* **Created:** When the chat ran.

Click any chat to see it in detail.

## Prompts

Navigate to **All** **Prompts** in your sidebar to see all the prompts you're tracking. They are grouped by **Topics** (or under **No Topic** folder if none assigned). At the top of the page, you'll see how many active prompts you have versus your plan limit.

Prompts are organized into three tabs:

* **Active:** Prompts Peec AI runs daily across the AI models.
* **Suggested:** Generated prompt suggestions with **Volume** data, suggestion date, and **Reject**/**Track** buttons.
* **Archived:** Paused prompts that you can reactivate at any time or permanently delete along with all their collected data.

Active prompts show these columns, in this order:

* **Visibility:** Percentage of chats mentioning the brand in the selected time period.
* **SoV:** The brand's mentions divided by all brand mentions across your prompts in the selected time period.
* **Position:** The brand's average position when mentioned in the selected time period.
* **Win rate:** Percentage of chats where the brand is ranked first in the selected time period.
* **Sentiment:** The brand's sentiment score when mentioned in the selected time period.
* **Mentions:** Brands mentioned in answers to this prompt or topic.
* **Volume:** Estimated search volume for a prompt relative to your industry. Hover over the colored bar to see the volume level, ranging from **Very low** to **Very high**.
* **Web Search:** Share of chats where the AI ran a live web search.
* **Links:** Share of chats whose answer links to a page in its own text, with the prompt's top linked domains beside it. Hover over the domains to see each one's share of the prompt's chats.
* **Branding:** Whether the prompt mentions your brand. See [Branded and Intent classification tags](/organizing-your-setup#branded-and-intent-classification-tags).
* **Intent:** The prompt's search intent: informational, commercial, or transactional.
* **Fact-checking:** Whether claims from this prompt are checked against your facts. See [Fact-checking](/brand-perception-fact-checking).
* **Tags:** Tags you've added to organize prompts.
* **Location:** The geographic location the prompt runs from.
* **Added:** When you created the prompt.

<Info>
  Use the column settings to hide or reorder columns, or to add the chat features that aren't shown by default, such as **Ads** or **Maps**. If you've saved your own column layout, it stays as you left it.
</Info>

### Individual prompt dashboards

Click any active prompt to see focused analytics for that prompt. You'll see the same layout as your main **Overview**, filtered to just that prompt.

Key differences:

* **No tag filters:** You're already viewing a specific prompt.
* **Top 7 brands:** How your brand is performing compared to your tracked competitors for this prompt. If they're not in the top 7, they'll appear at the bottom of the table with their actual ranking (e.g., #36).
* **Query fanouts** (only available for ChatGPT, Perplexity, and Copilot): The latest tracked fanout queries, so you can see what similar queries the model ran while creating the answer. For a more granular view, open the **Fanouts** tab in your sidebar.
* **Common terms**: The terms used most often across the fanout queries.
* **Links:** The domains and pages this prompt's answers link to, in the same cards as the [Links](#links) section on your **Overview**.
* **Recent chats in table format:** Shows recent responses in a structured table.

This gives you a more detailed view of how individual prompts perform and which competitors appear most often for specific questions.

### Query fanouts

To see a detailed breakdown of fanout queries, open the **Fanouts** tab in the sidebar.

<img alt="Fanouts" />

### What the page shows

AI models often run background searches before generating a response. The two stats at the top summarize those searches for the selected time period.

* **Distinct fanout queries:** The number of unique fanout queries generated for the selected filters.
* **Total occurrences:** The total number of times those fanout queries were issued.

Below the stats, the **All queries** list shows every fanout Peec captured, broken down by the topics you are tracking. Each row carries three things:

* **AI Model:** The AI model that triggered the fanout query.
* **Query:** The exact background search the AI ran.
* **Type:** What kind of fanout it was, “Search, Shopping, or Synthetic”.
* **Occurrences:** How many times that query fired across your chats within the selected time period.

Use **Group by** in the top right to switch between two views:

* **Topics (default):** Queries rolled up under each Topic, with a count beside it (for example, "Reputation questions" with 1,557). This is the fastest way to see what AI searches for in each area you track.
* **Prompts:** The same queries organized by the Prompt that triggered them, for when you want to trace fanouts back to a specific question.

### Brand visibility vs source visibility

Understanding the difference between these two is important:

* **Brand visibility:** Your brand is explicitly mentioned in the response generated by the AI model.
* **Source visibility:** Your domain or content was used as a source or cited, even if your brand name was not explicitly mentioned.

You can be visible as a source without being visible as a brand, and you can be mentioned as a brand without your website being used. Peec AI tracks both, so you can identify gaps. For example:

* If you're cited often but never mentioned, it might mean your brand lacks authority or name recognition.
* If you're mentioned often but never cited, AI might associate your brand name with a topic, but not trust your content as a reference.


# Upload and manage your products
Source: https://docs.peec.ai/uploading-products

Connect your product catalog to Peec to understand how each product performs across AI Shopping recommendations.

<img alt="Image" />

AI Shopping shows how individual products in your catalog perform across AI models, including which products are recommended, where they rank, which competitors appear alongside them, and how their performance changes over time.

This guide walks you through everything you need to connect your catalog and start product-level tracking. You’ll learn what product data Peec AI needs, the three ways to import your catalog, and the required CSV format for uploads.

Once your catalog is live on the **Products** page, Peec will begin building visibility, ranking, and competitor insights as new AI runs are completed.

## How to add your product catalog

To track product-level visibility, Peec AI first needs a clear view of your catalog, what products exist, which brand they belong to, and how they're categorized.

Once that's in place, AI mentions can be attributed back to the correct products. There are **three** ways to import your catalog:

* **Shopify storefront:** Paste your store's domain, and Peec AI pulls the catalog directly from your public `products.json` feed. This is the fastest path, and no file is required.
* **Peec CSV:** A flat file with one product per row, in our recommended format. Best for catalogs that aren't on Shopify.
* **Google Merchant Center feed:** Your existing product data feed (CSV, TSV, or JSON). Useful when you already maintain one for Google Shopping.

All three land in the same place: products show up on the **Products** page, organized by the categories you provide, and become filterable across the Shopping overview.

1. Go to **Shopping → Products** in your sidebar.
2. Click **Add products** in the top right of the products table.
3. Pick **CSV** in the dialog, then drag and drop your file or click to browse.
4. Confirm the preview matches what you expect, then click **Upload**.

### CSV format

A flat CSV with one row per product. The required columns are `title` and `brand`; everything else is optional but recommended.

| Column | Required | Description |
| :- | :- | :- |
| `title` | Yes | Product name as you'd want it to appear (e.g. "Peec Logo Hoodie"). |
| `brand` | Yes | Brand or vendor name. Used to group products and resolve to a canonical brand. |
| `description` | No | Free form product description. |
| `price` | No | Decimal string (e.g. `59.00`). |
| `currency` | No | ISO 4217 three letter code (e.g. `EUR`, `USD`). |
| `link` | No | Product detail page URL. |
| `imageLink` | No | Primary product image URL. |
| `category` | No | Category path separated by `" > "`, e.g. `Apparel > Hoodies`. Any depth is allowed. |

<Info>
  [**Download this example CSV**](https://app.peec.ai/Peec%20Shopping%20CSV%20Template.csv) to get started. Please make sure your file is UTF-8 encoded and uses commas as the field separator.
</Info>

Good `category` values matter: categories drive the breakdowns on the Shopping overview and the filters on the Products table. If your catalog already has a category tree, mirror it here.

Peec AI processes your catalog in the background. Products start appearing on the **Products** page within a few minutes, and per-product visibility, position, and competitor signals fill in as the next AI model run completes.

### Google Merchant Center

Peec AI also accepts the standard Google Merchant Center product feed as is (CSV, TSV, or JSON). The full list of columns and accepted values is documented in the [**Google Merchant Center product data specification**](https://support.google.com/merchants/answer/7052112).

### Shopify storefront

If your store runs on Shopify, you can paste your storefront domain (e.g. `your-store.myshopify.com` or your custom domain) in the **Shopify store** tab of the Add products dialog. Peec AI will fetch the full catalog from `products.json`, no file upload required.

## Manage your catalog

Your catalog can continue to grow and change after your first import. Switch between products in your catalog and those discovered in AI chats, add discovered products to your catalog, or remove products you no longer want to track.

You can also use **AI Shopping** without uploading a catalog, allowing you to explore products discovered directly from your tracked chats.

### My catalog vs. All products

The **Products** page and the **Overview** have a source switch in the top right.

* **My catalog:** This will show only the products you uploaded.
* **All products:** This will show every product Peec AI sees in your tracked chats, both yours and your competitors'.

You don't need to upload a catalog to get value. Switch to **All products** to see the full competitive field from your chats right away. Uploading your catalog adds products the AI hasn't mentioned yet, along with the catalog price and your own category structure.

### Reviewing categories during upload

When you upload a catalog, Peec AI automatically creates a category tree based on your product data. Before anything goes live, you can review the categories, make any necessary adjustments, and confirm them. Your products will then appear on the **Products** page, organized into those categories.

<Info>
  Categories are used across AI Shopping for filters and performance breakdowns, so take a moment to make sure they’re organized correctly before confirming.

  Uploading another CSV adds the new products to your existing catalog without replacing anything. If you only want to add one product, simply upload a CSV containing a single row.
</Info>

### Removing products

Select one or more products on the **Products** page and delete them. They disappear from your catalog views. Products discovered in chats stay visible under **All products**.

<Info>
  After an upload, Peec AI matches your products against chats from the previous 30 days. This gives you historical visibility, position, and competitor data from the start, rather than waiting for new chats to build up.
</Info>


# URLs
Source: https://docs.peec.ai/urls



<Frame>
  <img alt="Image" />
</Frame>

In the **URLs** page, you can identify specific pages that consistently influence AI responses and discover content formats that perform best in your industry:

* **Source retrievals over time:** Shows trends over time for the top 5 URLs, helping you track which specific pages gain or lose influence with AI models.
* **URL movers graph: L**ists URLs sorted by number of retrievals. You can toggle through different views:
  * **Top:** URLs with the highest number of retrievals in the selected timeframe
  * **New:** URLs retrieved for the first time in the selected timeframe
  * **Trending:** URLs showing the fastest growth in retrieval activity
  * **Losing:** URLs showing the largest decline in retrieval activity
* **Sources Type chart:** A category breakdown covering website page types, such as Article, Comparison, Listicle, Product Page, and others.

In the **URL** table below, you’ll find:

* **URL:** The exact webpage used as a source.
* **URL Type:** Automatic classification of the specific page type (Homepage, Article, Listicle, Comparison, Profile, etc.).
* **Mentions:** Which brands were mentioned on this specific URL.
* **Retrievals:** Total number of times this URL appeared as a source across all chats.
* **Citation Rate:** Average number of times the URL was explicitly cited when used (in your selected time period).
* **Updated:** The latest time we fetched content from this URL.

As with the **Domains** tab, toggle **Gap Analysis** to see content gaps and opportunities at the URL level. Higher scores indicate bigger opportunities — URLs that appear frequently and mention lots of competitors represent your best targets.

## URL types

**URL Type** offers a more granular classification by identifying the specific type of content on a given page. This allows for a deeper analysis of the context in which your brand is mentioned.

| **Type** | **Description** |
| :- | :- |
| **HOMEPAGE** | The main entry page of a website |
| **CATEGORY PAGE** | A page that lists products, articles, or subcategories |
| **PRODUCT PAGE** | A page detailing a single product or service |
| **LISTICLE** | An article structured as a list (e.g., “Top 10 Laptops of 2024”) |
| **COMPARISON** | An article or page that directly compares two or more products or services |
| **PROFILE** | A directory-style entry for a company, person, or product (e.g. G2, Yelp, Crunchbase) |
| **ALTERNATIVE** | An article focused on alternatives to a specific product or service (e.g., “Best HubSpot Alternatives”) |
| **DISCUSSION** | Content from discussion forums, comment sections, or community threads |
| **HOW TO GUIDE** | Instructional content with step-by-step guidance on completing a specific task |
| **ARTICLE** | General articles, news pieces, features, and other editorial content |
| **OTHER** | Any page type that does not fit into the categories above |

### Changing URL classification

Peec automatically classifies every URL based on its content, but we know your taxonomy may differ from ours. For example, a URL we label as “Product Page” might actually be a “Listicle”. With custom classification, you can now apply your own labels to every URL.

You can override this at any time:

1. Find the URL in the **URL table.**
2. Click the classification label on that row (e.g., Listicle, Comparison, etc.).
3. A search-first picker opens, search existing types (including any custom ones you've created), or create a new one inline.
4. The override saves immediately and appears everywhere the source appears.

<Frame>
  <img alt="URL Domain Classification" />
</Frame>

## URL metrics

On the URL page, you will see key metrics such as **Retrievals** and **Citation Rate**.

<Frame>
  <img alt="Untitled Design (11)" />
</Frame>

### Retrievals

Retrievals is the total number of times a URL was used as a source, regardless of whether it was cited directly in the AI’s main answer. This metric indicates which URLs are most popular and most credible to AI models.

Retrievals over your selected timespan are calculated as:

`Retrievals (URLs) = Total responses where URL was used as a source`

### Citation rate

Citation Rate measures the average number of times a specific source is explicitly cited within AI responses over the last 7 days. This metric indicates how often AI models find your content relevant enough to reference multiple times.

Multiple citations in a single response indicate that AI models consider your content highly relevant and trustworthy for the topic at hand.

The citation rate is calculated over your selected timespan as:

`Citation Rate (URLs) = Total citations of that URL / Total responses where URL was used as a source`

## URLs detail page

When you open the **URLs** section, you see a list of pages that have been used as a source by the different AI models in their answers. Clicking any URL takes you to its **Detail Page,** providing further insights into how the models have used it.

You can open this detail page for each URL by clicking it.

<Frame>
  <img alt="URL Detail Page" />
</Frame>

Click **"View page content"** in the header to open a dialog showing the full text Peec retrieved from this URL. This is the same content that AI models read when they use this page as a source. Alternatively, you can click the URL to be redirected to the page where the content is located.

The **URL Detail Page** will show you the following information:

1. **URL and Title:** The page title that is being pulled as a source, and the URL that you can visit.
2. **URL Overview:** Different metrics and information, such as citation rate, retrievals, number of prompts currently using the page, and first and last time the URL was seen, with their respective absolute change compared to the previous period you are filtering for.
3. **Retrievals Chart:** Line chart showing the number of times that URL appeared as a source in AI answers over time (by default, 7 days) and the respective period comparison
4. **Retrievals by Model:** Bar chart breaking down retrievals by the AI model you are currently tracking
5. **Prompts Table:** Which prompts triggered this URL as a source, regardless of whether it was cited or not, and to which topic does that prompt belong
6. **Brands Mentioned:** Which brands appear in the source content, and how frequently
7. **Chats: T**he actual AI answers where this URL was cited or used as a source

You can use this information to:

* Track citation changes over time to know when to push more content on a topic, or pull back.
* Compare model usage across periods to decide where to optimize
* Study the prompts driving citations to reverse-engineer what questions are making this source relevant

## Bookmarking URLs

Within Peec, you can bookmark URLs to build a personalized watchlist of sites you want to monitor closely, such as key competitors, your top owned assets, target publications for outreach, or any other URLs that matter to you.

**Bookmarking a URL is simple**: Every source row has a **bookmark icon i**n the left column. Clicking it adds the source to your watchlist under the tab **Bookmarked**.

<Frame>
  <img alt="Bookmarking UR Ls" />
</Frame>

You can then quickly toggle between your bookmarked and non-bookmarked sources. Great for running a quick check on your priority sources without having to scroll through everything.


# Use cases
Source: https://docs.peec.ai/use-cases



Below are some ways you can use **Agent Analytics** to improve your visibility and performance in AI search.

## Standalone log file-based benefits & use cases

1. **See which AI bots are visiting your site:** Server logs show which bots are accessing your website, how often they visit, and which pages they crawl. This lets you confirm whether AI crawlers are reaching your site without relying on prompt tracking.
2. **Detect crawl anomalies and technical access problems:** Spikes, drops, or 4xx/5xx errors on bot requests are visible in logs. If a bot suddenly stops requesting, or is hitting errors on key pages, you can catch and fix that before it ever becomes a source-visibility problem.
3. **Audit robots.txt compliance:** Logs let you verify that bots are actually respecting your directives, or flag when they aren't. The Crawlability feature helps you understand your robots.txt directives. This is a technical governance use case that stands entirely on its own.
4. **Understand crawl depth and site structure discovery:** Which sections of your site are bots exploring deeply vs. skimming? Logs show frequency patterns across your folder structure - useful for understanding how AI bots navigate your site architecture, independent of what ends up in answers.
5. **Establish a baseline before you do anything else:** Log data is available from day one (if you connect to a source or upload a file), before you've even set up any prompt tracking. It can serve as a starting point for any AI visibility program, giving you a factual picture of bot activity.
6. **Monitor the impact of technical changes independently:** When you update your sitemap, fix crawl errors, or adjust your robots.txt, logs let you observe whether bot behavior changed - without needing to wait for prompt tracking data to reflect downstream effects.

## Combined log file and prompt tracking benefits

1. **Separate access from impact:** Logs tell you what bots requested. Prompt tracking tells you what actually surfaced in AI answers. Together, they answer the question that logs alone can't: "Is the bot's interest in this content translating into real AI visibility?"
2. **Diagnose underperformance more precisely:** When a heavily crawled page rarely appears as a source, the combined view helps you distinguish between three very different problems: a technical access issue, a content quality issue, or simply a gap in your prompt tracking setup. Each has a different fix.
3. **Use log activity to pressure-test your tracking coverage:** Prompt tracking only reflects the topics you've chosen to monitor, so it has an inherent blind spot. Log data can surface content areas receiving significant bot attention that your currently tracked prompts don't cover, giving you a concrete signal to expand your tracking before drawing conclusions about content performance.
4. **Make optimization decisions with stronger evidence:** Either signal alone might mislead. High request volume without source data looks like success. Low source usage without log data looks like a failure. Together, they let you prioritize with more confidence and evaluate whether changes you make are actually moving the needle on both sides.


# Video library
Source: https://docs.peec.ai/video-library

For those who prefer the video format, this is a collection of all of the videos we've linked in this Product Documentation.

## Intro to Peec AI

<iframe title="YouTube video player" />

[Watch "Welcome to Peec AI" on YouTube](https://youtu.be/FfF7rCUayEc)

## Quickstart Guide

<iframe title="YouTube video player" />

[Watch "Peec AI Product Walkthrough" on YouTube](https://youtu.be/CT4aKlOouFQ)

## Setting up your prompts

<iframe title="YouTube video player" />

[Watch "Setting up your prompts" on YouTube](https://youtu.be/wcbmAs4Q-oE)

## Organizing your setup

<iframe title="YouTube video player" />

[Watch "Organizing your setup" on YouTube](https://youtu.be/_9Z43OpAumM)

## Identifying your competitors

<iframe title="YouTube video player" />

[Watch "Identifying your competitors" on YouTube](https://youtu.be/sS9tgmX1naw)

## Understanding chats

<iframe title="YouTube video player" />

[Watch "Understanding chats" on YouTube](https://youtu.be/EnxfmarTlrg)

## Understanding your performance

<iframe title="YouTube video player" />

[Watch "Understanding your performance" on YouTube](https://youtu.be/xuXNzv51Mjo)

## Understanding sources

<iframe title="YouTube video player" />

[Watch "Understanding your sources" on YouTube](https://youtu.be/OOh0SVkKN4w)

## Managing Your Project

<iframe title="YouTube video player" />

[Watch "Managing your project for brands" on YouTube](https://youtu.be/2bJ9OZy2-cE)

## Crawl Insights

<iframe title="YouTube video player" />

[Watch "Agent Analytics - Peec AI" on YouTube](https://youtu.be/xr099LCVWhg)

<iframe title="YouTube video player" />

[Watch "Agent Analytics - Connecting to Cloudflare" on YouTube](https://youtu.be/5y3ZZfTEfMQ)