# 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.
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.
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.
## Ads overview
![Screenshot 2026 07 16 At 13 13 57]()
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 prompts 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.
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.
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
![Ads Table]()
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.
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.
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.
In the Prompts view, you can filter by whether your brand is mentioned.
![Ads By Topic]()
## 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.
Our agency plans focus on flexibility and scale. You're likely tracking not just one brand but multiple client projects simultaneously, each with its own set of prompts, competitors, and goals. Our credit-based system gives you the freedom to allocate resources between those clients. Think of credits as your currency to assign prompts and models to projects.
## Understanding agency plan credits
Each agency plan provides a fixed amount of credits that you can allocate to different client projects. They determine how many prompts you can run across how many models and in what frequency across your client base.
In the Projects tab in your sidebar, you can see how many credits are already assigned to active customer projects and how many are still available in your plan.
Running one prompt against one AI model for one day costs 1 credit.
We think in months, so one prompt on one model for the whole month will allocate 30 credits on your project.
Our 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**
Consider the following scenario:
**Your plan**: Growth with 25,000 credits 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**\
Remaining: 9,250 credits *(can be allocated to existing projects to add more prompts, models, or can be used to add new client projects)*
Credits let you decide how many prompts and models to track per project, giving you full control over your customer projects.
**Credits aren't spent or consumed**. They are allocation slots of how many credits you assign to each projects automatically adjusted based on the prompts and models you are tracking.
Those allocations remain in place and don’t reset each month. You can adjust them at any time.
## Choosing your plan
Peec AI offers four agency plans designed to match your client portfolio and monitoring scale. They differ in the number of credits they offer, project slots, and feature access:
* **Essentials** (10.000 Credits): Built for small agencies or teams that are getting started with AI visibility tracking and already have \_s\_ome clients on board.
* **Growth** (25.000 Credits): Designed for agencies actively building their AI visibility service offering as prospects increase.
* **Scale** (65.000 Credits): Built for established agencies managing larger portfolios. This tier includes API access for custom integrations.
* **Comprehensive** (custom # of Credits): Designed for agencies running AI visibility as a core service line. This tier also includes API access and adds dedicated support to ensure your team operates efficiently at scale.
# Managing your projects
Source: https://docs.peec.ai/agencies/managing-your-projects
[Watch "Managing your project for agencies" on YouTube](https://youtu.be/cV3u43Pittg)
Managing your client projects doesn’t have to be complicated. In Peec, you can easily track, adjust, delete, create, and perform other actions on your client projects under the **Projects tab**. Whether a client needs more tracking capabilities or you need to create a new space for a newly onboarded client, everything can be done here.
## Creating Projects
In the Projects tab, you can easily create both **customer** and **pitch** projects in just a few clicks. Whether you’re setting up a new project for a new client or creating one for a prospect who is interested but not yet ready to commit, both project types can be created quickly and easily.
### Creating a customer project
To create a customer project:
1. Navigate to **Projects** in the side panel
2. Click **Add new project**
3. Select **Customer project** from the modal
4. Fill in the required information
5. Select the number of prompts that you wish to track (the summary will automatically adjust based on your changes to reflect the amount of credits needed)
6. Select the models that you want to run
7. Click on **Continue**
![Creatingnewproject Agency 1]()
### 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**
![Creating Pitch Project 1]()
## 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.
![Prompt Adjusting 1]()
### 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**
![Adjusting Models Agencies]()
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.
![Pitch Customer Convert 1]()
### 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**
![Downloadingchats Agency]()
## 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**
![Pausing Project Agency]()
## 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.
**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.
# Understanding credits
Source: https://docs.peec.ai/agencies/understanding_credits
How agencies can use credits to allocate prompts and models to their projects
[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.
Our 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**
For our larger plans, such as Scale and Comprehensive, you can switch to weekly tracking for 1/3 of the credit use.
For example, tracking the prompt: **"What's the best CRM for small businesses?"** daily across three AI models (ChatGPT, Claude, and Perplexity) for a full month would require 90 credits:
1 prompt x 3 AI models x 30 days = 90 credits
## Managing your credits
### Usage overview
You can see how many credits are available and how many are currently assigned to active customer projects in the **Projects** tab under **Usage.**
**Usage** tells you:
* The total number of already assigned credits
* The total number of available credits for your subscription plan
* Colored breakdown of projects by the number of credits assigned to each
You can hover over each colored box to quickly see how many credits are being used and how many are assigned for each project. You can also always see this in the project table below.
Don’t worry about having to calculate how many credits you will need for each new project. We will automatically do this for you when you create a new one.
![Clean Shot 2026 03 04 At 14 28 52@2x]()
### Project table
The project table gives you a quick overview of the current status of all the projects on your account, split between **Customer** and **Pitch.**
This is where you can manage the number of prompts and models each project should track. You can also delete a customer or a pitch project if it's no longer needed.
![Projects Table]()
The projects table will show:
* The name of your project (this is the name used internally to identify the project you are working on)
* The domain being used for the project
* **Used** and **Allocated** prompts for each project
* All the models that are currently being tracked
* **Used** and **Allocated** credits based on the prompts and models being tracked per project
* The frequency at which the project runs (Daily means we run the prompts every 24 hours). For Scale and Comprehensive plans, this can be adjusted to Weekly)
* The date when the project was created
* The status of the project (**Customer, Pitch, Pitch Ended)**
* Setting options to update your brand details, changing tracking, or deleting the project
This view also applies to the Pitch project under the **Pitch tab**.
# 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 all brand-perception runs — there is no date range.
# 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). 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 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 all brand-perception runs — there is no date range. Pagination applies to attributes.
# 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. Optionally pass a country_code to override the suggestion's country for the created prompt.
# 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
# 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
# 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.
# 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 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
# 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 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 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.
## 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)`
## `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.
## 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)`
## `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 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.
## Aggregation Formulas
When aggregating results across multiple rows/dimensions, use the following formula:
- **citation_rate**: `sum(citation_count) / sum(retrieval_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 isolating 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.
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.
### 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
### 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`.
### 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.
### 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.
### 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`.
### 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.
### 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`.
### 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.
### 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.
### 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`.
### 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.
### 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).
### 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`.
### 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.
### 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`).
### 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.
### 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.
### 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.
### 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.
### 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).
### 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.
### 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.
### 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.
### Added
* **`chat_id` Dimension and Filter on Report Endpoints** All report endpoints now support `chat_id` as a dimension and filter.
### 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.
### 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.
### 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.
### 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.
### 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.
### 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.
### 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.
### 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.
### 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.
### 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.
### 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.
### 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.
### 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.
### Added
* **Initial Release** The Peec Customer API is now available.
# 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`.
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.
## `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.
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.
## 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`.
Filtering by `brand_id` in `filters` always reports `share_of_voice` as `1.0`. That number is meaningless.
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 carry **multiple tags**. (Topics are different: each prompt belongs to exactly one topic, so topics don't overlap.)
When you break a report down by `tag_id`, a chat whose prompt has three tags contributes to **all three** tag results. That's exactly what you want when comparing tags against each other, since each tag's number reflects everything labeled with it.
The trouble starts when you take those per-tag results and add them up yourself to get a total. Because overlapping chats were counted under every tag they belong to, your hand-rolled total counts them multiple times and overshoots the truth.
Never sum tag-level results to get a project total. A chat tagged `enterprise` and `q4-campaign` is counted under both, so adding the two tag results double-counts it.
The fix is simple: **let the report do the aggregation.** Request the report *without* the `tag_id` dimension (or with no dimensions at all) and Peec aggregates over distinct chats, counting each one once:
Request once without `tag_id`. Each chat is counted a single time.
Request broken down by `tag_id`, then add the results together. Multi-tagged chats are counted once per tag.
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.
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.
# Introduction to Peec API
Source: https://docs.peec.ai/api/introduction
This API is currently in beta. Endpoints, payloads, and responses may be updated as we refine it.
Access to this API is currently limited to Enterprise customers.
## 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.
## 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.
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.
## 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.
These limits may be adjusted. Please adhere to the response headers.
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 perception
Source: https://docs.peec.ai/brand-perception
How AI describes your brand, and how a single brand performs across every dimension you track.
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 gives you two connected views for this:
* **Brand Perception**: Breaks AI's view of your brand into attributes, the qualities models associate with brands in your space.
* **Brand Insights:** Zooms into a single brand and shows how it performs across models, topics, geographies, and competitors.
## Brand Perception
Peec 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.
![Screenshot 2026 07 29 At 17 11 52]()
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.
### 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.
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.
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.
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 by which your brand is measured and compared (You can display up to three brands simultaneously and select which attributes to compare against).
* **How AI describes your brand:** Attribute mention chart that shows you 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.
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?"
### 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.
# Connecting your data
Source: https://docs.peec.ai/connecting-your-data
Crawl Insights works on your server logs. Connect a data source and Peec identifies the 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**.
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.
## AWS CloudFront
Peec 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 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 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
![Connecting To Cloudflare]()
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 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 such situations:
* **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 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 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 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 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**.
Regenerating the API key invalidates the previous one. Update your sender configuration before switching keys.
### Endpoint
```text theme={null}
POST https://api.peec.ai/agent-analytics/generic-access-log
```
### Required headers
```text theme={null}
Authorization: Bearer
x-org-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 |
# 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.
[Watch "Agent Analytics - Peec AI" on YouTubeWatch "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 visibilityCrawl 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, navigate to **Crawl Insights** in the side panel and connect a data source. We support automated integrations for **AWS CloudFront**, **Google Cloud CDN**, **Cloudflare**, **Vercel**, **WordPress**, and **Akamai**, plus a **generic webhook** and direct **CSV/CLF file upload**o get started, navigate to **Crawl Insights** in the side panel and connect a data source. We support 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](/connecting-your-data).
The setup steps for every option are in [Connecting your data](/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 will appear. Here, you can access key information and use different tools to analyze your data.
![Crawl Insights Dashboard]()
In the dashboard, you will be able to see:
* **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 you a snapshot of your filtered data based on total bot visits, active bots, and failure rate (e.g., proportion of requests that returned an error (4xx or 5xx))
* **Crawl activity over time:** The line chart shows AI bot visits, with a separate line for each AI model. Switch between hourly (only visible in a 3-day view), daily, weekly, and monthly views - daily is the default. Use this 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
The crawl breakdown will show you a set of bar charts that break down bot visits by different dimensions.
![Crawl Breakdown]()
These dimensions are:
* **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
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.
## Detailed Insights
Insight Details provides a URL-level breakdown of AI bot activity and source performance. You can access it from the in-page navigation bar or by clicking the See Details button above the By URL chart.
In 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 actively indexed, with detailed information for each. This will give you a quick overview of which pages are receiving bot visits, how often they occur, and how this varies across all bots currently visiting those pages.
You will 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
Additionally, based on your prompt data, you will also be able to see:
* **Retrievals**: The sum total of how many times this URL appeared as a source in AI chat responses
* **Citation rate**: 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
Prompt data comes from the prompts you are tracking. It is not influenced by AI bot activity.
## Settings
Under Settings, you can easily manage your connection to Cloudflare or any other provider. If you need to connect a new provider, you can easily disconnect and connect to ensure a seamless migration and avoid data gaps.
You can also delete all of your log file data. Please note that this action is irreversible and the data can not be recovered.
![Crawl Settings 1]()
## 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 if they have zero visits in your log data. 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
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).
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.
Agent Analytics is currently available to all accounts. Usage limits may be introduced in the future as we continue to scale the feature.
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.
You can request the deletion of your data at any time by contacting our support team or navigating to settings in the danger zone.
## Privacy policy
To find more about our privacy policy, go here: [Privacy Policy for Peec AI](https://peec.ai/legal/privacy-policy)
# Crawlability
Source: https://docs.peec.ai/crawlability
Crawlability shows you which AI bots are allowed or blocked by a site's robots.txt file. Select a tracked domain and get results instantly with no setup or account connection required.
Peec checks the domain's robots.txt against 40+ AI bots from 20+ vendors, then shows you the status for each.
We categorize bots based on publicly available data and their stated purpose. As real-world behavior becomes clearer, categories may be refined to ensure accuracy.
## Crawlability table
The table breaks down the status for each individual 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
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.
## URL Tester
![Crawlability URL Tester]()
Here you can enter any URL to see which AI bots are allowed or blocked by your domain's robots.txt rules.
Simply choose a URL from your domain to analyze and see which bots are allowed or blocked from crawling it. You can then use this insight to troubleshoot if bots are unintentionally blocked or to enable crawlability for it.
## Interpreting Crawlability
If a bot is blocked, it can't access your content. This means it can't use your site as a source in its responses.
Use Crawlability to:
* Catch accidental blocking before it affects your AI visibility
* Understand which AI ecosystems can and can't access your content
* Verify that changes to your robots.txt are working as expected
## Bots
The Bots show you which specific bots from which vendors are accessing and visiting your pages, and the type of each.
| 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 | Meta | 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. |
# Domains
Source: https://docs.peec.ai/domains
## Domain overview
![Untitled Design (10)]()
In the **Domains** page, you’ll see:
* **Source Retrieval by Domain graph:** Shows trends over time for the top 5 domains. Hover over the chart to see which domain each line represents and track how source retrieval changes over your selected timeframe.
* **Sources Type chart:** Displays the number of citations by domain category (Editorial, Corporate, UGC, etc.). This helps you understand which types of sources dominate your industry and where to focus your optimization efforts.
* **Domain movers graph: L**ists domains sorted by number of retrievals. You can toggle through 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 Table:** Displays all domains that have contributed to generating answers to your prompts, sorted by retrieval rate (from highest to lowest).
## Domain table
The domain table shows:
* **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.
* **Total citations:** The total number of times this URL was cited across all responses in your selected filters and time period.
* **Citation share:** This domain's share of all citations in the current view: its total citations divided by the total across every domain matching your filters, shown as a percentage.
* **Citation rate**: Average number of times the domain was explicitly cited when used in your selected time period.
* **Gap Analysis toggle:** Content gaps and opportunities based on the **Gap Score** column.
**Gap Analysis:** Higher scores indicate bigger opportunities — sources that appear frequently and mention lots of competitors represent your best targets.
## Domain types
**Domain Type** provides a high-level categorization of the entire domain or website. This helps you understand the general nature of the source at a glance.
| **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 automatically classifies every domain and URL it tracks as shown above. But your taxonomy might not match ours. A domain we label "Editorial" might be a key partner to you. With custom classification, you can now apply your own labels.
You can override this at any time:
1. Find the domain in the **Domain table.**
2. Click the classification label on that row (e.g., Reference, Editorial, 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.
![URL Domain Classification]()
Overridden rows are visually marked so you can always tell what's been manually set versus auto-detected. You can reset any override back to the original automatic classification at any time.
## Domain metrics
In the domain table, you will see key metrics such as **Retrieved**, **Retrieval Rate**, **Total Citations**, **Citation Share,** and **Citation Rate** metrics. 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 timespan 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, on average, how many times a URL from a specific domain is retrieved per chat. Values above 1.0 mean the AI is pulling multiple pages from that domain in a single conversation. This metric reveals depth of reliance; not just whether your domain shows up, but how heavily the AI leans on it.
A brand with a high retrieval rate is deeply embedded in AI responses, not just occasionally present.
Note: A single chat can retrieve multiple URLs from the same domain.
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 is calculated over your selected filters and timespan 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.
### 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 timespan 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 measures the average number of times a specific source is explicitly cited within AI responses. 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 (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, you can bookmark domains 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 domains that matter to you.
**Bookmarking a source 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**.
![Bookmarking Domain]()
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.
# Get inspired by Actions
Source: https://docs.peec.ai/get-inspired-by-actions
Learn how Actions translate source-level data into clear opportunities to improve your AI visibility.
[Watch "Get inspired by Actions" on YouTube](https://youtu.be/BmrjdGO2OQw)
## What are Actions?
Actions group similar sources together so you can see exactly where to improve your AI visibility. For example, all editorial listicles form one Action, while Reddit discussions become another.
Instead of scrolling through hundreds of URLs, you get clear opportunities organized by what you can actually do about them. Each Action gives you specific steps to strengthen your presence — like publishing new content, optimizing existing pages, or engaging with channels AI models already trust.
Every Action includes tailored recommendations describing what you can do right now to strengthen your visibility in that specific content space. These suggestions highlight practical steps you can take: publishing new content, optimizing existing pages, creating comparable assets, or engaging with channels the models already trust.
Actions give you everything in one place: what to do, why it matters, and how to do it
We create Actions by grouping sources with similar formats or purposes, showing you where you show up and where competitors appear but you don't.
## Relative Opportunity Score
Instead of complex metrics, each Action has a **Relative Opportunity Score** from 1 to 3 showing the potential to improve your visibility by taking that Action.
The score is based on two factors:
1. **Source Usage:** How often the AI models you track have used this source in their responses.
2. **Brand Presence:** How much you appear in these sources compared to your competitors.
Higher scores mean AI models use these sources frequently, but your competitors appear there more than you do — making it a strong opportunity for you to increase your visibility.
| Score | Meaning |
| :---- | :--------------------------------------------- |
| **1** | Low relative opportunity for your project |
| **2** | Moderate relative opportunity for your project |
| **3** | High relative opportunity for your project |
## Finding the right Action for your goal
Your strategic goals might focus on specific markets, products, or AI model performance. Use filters to focus on Actions that match your current priorities.
You can filter Actions by:
* **Date**: Analyze performance and opportunity trends over specific time periods.
* **Tags**: Focus on Actions related to specific tags associated with your tracked prompts.
* **Model**: Target Actions where a specific AI model (e.g., ChatGPT, Gemini, Perplexity) shows the greatest opportunity gap.
* **Topics**: Filter by topics relevant to your current focus area, such as product categories or industry segments.
* **Countries**: Narrow down opportunities to specific geographic markets where you want to boost visibility.
## Action groups
Actions are split into two groups (**On-Page** and **Off-Page) based on** where you can improve visibility.
### On-Page
**Owned**
Owned Actions group together pages controlled by you or your competitors, organized by content type (Article, Product Page, Listicle, How-To Guide, etc.). They show where competitors' content gives them an advantage.
### Off-Page
**Editorial**
Editorial Actions include articles, guides, comparisons, reviews, and listicles from third-party publishers. They reveal which publishers and writers influence AI replies.
**User-Generated Content (UGC)**
UGC Actions focus on high-impact communities like forums, Q\&A sites, and other discussion platforms.
They help you understand audience language and where competitors have organic engagement advantages.
**Reference**
Reference Actions capture structured or semi-structured informational sources, like encyclopedias, glossaries, definitions, indexes, and knowledge hubs.
These sources often become "anchor content" in model understanding. Strong competitor presence here signals you should add more structured, factual content.
# Identifying your competitors
Source: https://docs.peec.ai/identifying-your-competitors
Track competitive performance and see who AI is promoting alongside (or instead of) you.
[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 provide benchmarks for your AI visibility and help define your ambition level. They also give your metrics meaningful perspective. Seeing 15% visibility becomes much more actionable when you know competitors achieve 45% for the same prompts — this shows both the opportunity size and what's achievable in your market.
Adding competitor brands helps you:
* **Set realistic benchmarks:** Understand achievable visibility levels in your industry.
* **Define ambition levels:** Decide whether to match, exceed, or dominate competitive performance.
* **Identify opportunities:** Spot prompts where competitors consistently outperform you.
* **Track market shifts:** Monitor new players gaining traction or established brands losing ground.
## Set up competitors
Navigate to **Brands** in your sidebar to add competitors through automatic suggestions or manual entry.
### Accept competitor brand suggestions
We detect brands mentioned alongside yours and suggest them when they appear at least twice. In the top section of **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** for how you want the brand to appear in your dashboard (not used for matching).
* Add **Tracked Name** for the term Peec AI will use to identify this brand in AI responses. Only the tracked name and its aliases are matched, not the display name.
* Add **Domain** for their main website (optional).
* Add **Regular Expression** for advanced pattern matching if needed (optional).
* Click **Create** to save.
## Manage Competitors
After adding competitors, you can refine their settings for accurate tracking. Click any competitor to access their detail page or go to **Brands** page in your sidebar. You can also do this for your own brand.
### Brand detail page
You can modify these settings for any tracked brands:
* **Display Name:** How the competitor appears in your analysis and dashboards. Customize this for clarity without affecting tracking.
* **Tracked Name:** The term Peec AI searches for in AI responses. This should be the shortest, unique version of the brand name that AI models typically use. **This isn’t case-sensitive.**
* **Aliases:** Alternative spellings, abbreviations, or variations that should count as mentions of this brand.
* **Advanced: Regular Expression:** Set pattern matching for complex detection scenarios. Use this when simple name matching isn't sufficient. **This is case-sensitive.**
* **Domain:** Website domain used to classify sources as "You" or "Competitor" in your analysis. Add alternative domains if the brand uses multiple websites.
* **Color:** Custom color for visual identification in graphs and dashboards. Find the color picker next to the brand’s logo.
Saving changes triggers a data update that may take a few moments to complete while we search all chats with the updated information.
### Control what counts as a brand mention
Use the tracked name, aliases, and RegEx fields to control what Peec considers a valid brand mention.
### **Basic naming**
Start with the shortest unique brand name. For example, use "BMW" not "BMW Deutschland," "HubSpot" not "HubSpot, Inc.," or "Slack" not "Slack Technologies." Focus on how people actually refer to the brand in conversation, not official company names.
### **Adding aliases**
Check recent chats to see how AI models reference competitors, then add abbreviations, alternative spellings, or partial names as aliases. This keeps tracking accurate as language patterns change.
### **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.
Simple RegEx examples:
* `(Apple|APPLE)` → Match only capitalized versions.
* `(Apple\\s)` → Match complete word "Apple", not part of "pineapple."
# Welcome to Peec AI
Source: https://docs.peec.ai/intro-to-peec-ai
The #1 AI search analytics tool for marketing teams and agencies.
[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 Grok, 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:** We'll help you get actionable insights about your AI visibility within your first week. First, you'll understand exactly what we track and how it's different from traditional search. Then, our quickstart guide walks you through your first setup — from creating prompts that mirror real questions users ask AI to identifying the right competitors and understanding your first results.
* **Set up your project:** You'll learn how to craft effective prompts for your industry, organize your tracking system with tags and categories, and identify which competitors you should be watching. This is where you build everything you need to start collecting meaningful data.
* **Interpret your results:** Once your prompts are running, you'll start seeing visibility data, position trends, and sentiment patterns. This section teaches 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 will generate 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
We track how your brand appears when people ask AI platforms questions about your industry. Instead of traditional search rankings, we measure three key things that matter in AI search: how visible your brand is, what position you typically 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 to other brands).
* **Sentiment** captures whether AI models describe your brand positively, neutrally, or negatively when they mention you.
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).
The basis for all these metrics are **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 actually respond.
## How Peec AI collects data
We run your prompts across AI platforms like ChatGPT, Gemini, and Copilot daily, then analyze 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 talk to AI tools.
Unlike traditional analytics tools that rely on APIs, **Peec AI uses advanced UI scraping technology** to interact with AI models exactly as real users do. This approach provides several key advantages:
* **Authentic user experience:** We interact with AI models through their web interfaces, capturing the same responses users see.
* **Real-world accuracy:** Our data reflects actual user experiences, not sanitized API responses.
* **Comprehensive coverage:** We can access models that don't offer public APIs or have limited API functionality.
Our UI scraping technology simulates real user interactions, ensuring the data we collect matches what the average user sees when they use these AI tools.
For most AI platforms, this means that they decide which model to use and if they perform a web search or not. This is the reality for a logged-out user and the approach that's closest to the average user's experience.
## Technical approach: UI scraping vs API access
### **Why we don't use APIs**
Most AI analytics tools rely on official APIs, but this 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 used in API responses can be different from those shown to real users.
### **Our UI scraping advantage**
Instead of APIs, Peec AI uses sophisticated browser automation to interact with AI models through their web interfaces:
* **Real user simulation:** We use the same interfaces your customers use, ensuring 100% authentic data.
* **Consistent data quality:** Every interaction follows the same user journey as real users.
* **Future-proof:** Our approach works regardless of API changes or restrictions.
This technical approach ensures that your visibility data reflects the real user experience, not a filtered or modified API response.
## How Peec AI helps
Peec AI shows you exactly 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.
Our analysis goes beyond basic mentions — you can filter by time periods, compare multiple competitors, and access all your data through exports, our [Looker connector](https://docs.peec.ai/looker/introduction) and our [API](https://docs.peec.ai/api/introduction) (limited to Enterprise plans for now) 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**
![Connecting To Looker]()
The Data Studio connector is available only to users with a valid Peec API Key in their account.
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.
## 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
[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
[Watch "Managing your project for brands" on YouTube](https://youtu.be/2bJ9OZy2-cE)
Managing your projects in Peec AI is straightforward. Everything is centralized in the **Projects tab**, where you can view the projects you’re currently working on, update tracking settings and project details (such as prompts, models, and names), and even delete projects when needed.
The **Projects** tab shows you all the relevant information you need for your project and lets you manage the prompts and models you are tracking with a few simple clicks.
In the Projects tab, you will see:
* The number of allocated and the maximum number of prompts you can track with your subscription
* How many prompts are currently being tracked for all your projects
* A list of all the projects you are currently running, with additional information on the prompts, models, and frequency at which the project is set up
## Updating your project
Updating your project is simple, and it only takes a few clicks to adjust what you need. Whether you need to adjust the prompt limit, the number of models you want to track, or remove a project, you can do all of that under the same tab.
### Adjusting 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 prompt limit.
* Click anywhere else on the screen to save the changes.
![Prompt Adjusting]()
Your pool of allocated prompts will adjust automatically as you increase or reduce the number of prompts per project.
### 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.
In the projects table:
* Find the project you want to update.
* Select the **Models** box in the project to open up the selector modal.
* Switch, add, or turn off any model
* Click **Update.**
![Adjusting Models]()
### Updating your project details
In the **Projects tab**, you can modify all the main details of your project. Whether you need a new name for your project so your colleagues can recognize it easily, or you want to 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
![Adjusting Details]()
### Exporting chats
If you need an export of all the chats for any given project in CSV format, you can download it from the **Projects** tab.
To export all chats:
* Click on the three dots in the right column
* Click on **Export Chats**
* Click on **Generate Export** and wait until the export is finished
* You can then download the file and use it for your analysis
![Downloading Chats]()
## Pausing your project
You can pause a 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.
When you pause a project, all prompts within it stop running, and the project stops collecting 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. After the project is resumed, prompts start running again, and new data begins to appear.
Allocated prompts will no longer count toward your limit and can be reassigned to other projects. If you resume later, you will need to allocate prompts again.
**Note:** Pausing a project is not applicable to Starter plans.
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**
![Pausing And Resuming A Project]()
# 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
Add the server URL to your AI tool. See our [setup guide](/mcp/setup) for your platform.
Authorize with your Peec AI account. This only happens once.
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.
## 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 ` 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.
The consent page shows which application is requesting access. You can switch accounts if needed.
## 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.
Prompts are versioned with the Peec AI MCP server. When we ship a new one, it appears in your client automatically. No install.
## 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 |
If prompts don't show up after connecting, remove and re-add the Peec AI integration to refresh the tool and prompt list.
## 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.
## 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"*
Prompts are read-only. They only use the same Peec AI data you can already see in the dashboard.
# 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
Sign in to [app.peec.ai](https://app.peec.ai) and go to **API Keys** in the sidebar.
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**.
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.
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)
Open Claude Desktop and go to **Settings** or \*\*Customize \*\*(gear icon), then **Connectors**.
Search for and click on the **Peec AI** connector and install it
Click **Connect**. You'll be redirected to Peec AI to sign in. Once authorized, return to the Claude Desktop.
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
![Connecting Claude MCP]()
## 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"
```
## Cursor
Open **Cursor Settings**, then go to **Tools & Integrations**, then **MCP**.
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.
Without a PAT, you'll be prompted to sign in via Peec AI when you first use the server.
## 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
Open **Windsurf Settings**, then go to **MCP**.
Click **Add Server** and enter the server URL:
```text theme={null}
https://api.peec.ai/mcp
```
You'll be prompted to sign in via Peec AI when you first use the server.
## 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 ` 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** (33) return data: projects, brands, model channels, prompts, chats, reports, actions, scraped source content, custom classifications, the brand profile, products and the shopping catalog, shopping performance/demand/trend metrics, the Peec documentation, and Agent Analytics (known bots and access-log visit counts).
* **Write tools** (43) create, update, archive, or delete brands, prompts, tags, tag groups, topics, products, categories, custom domain/URL classifications, and the brand profile. Your assistant confirms before calling one.
Your AI assistant calls these automatically based on your questions. You don't need to invoke them directly, but this reference helps you understand what is available.
All tools except `list_projects`, `search_docs`, and `read_doc` require a `project_id`. Your AI assistant handles this automatically after you pick a project.
Write tools require organization-owner 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.
## 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) |
**Columns:** `id`, `name`, `domains`, `aliases`, `is_own`
`aliases` are alternate names the brand is matched under. `is_own` indicates whether this is your brand (`true`) or a competitor (`false`).
***
## 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.
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.
***
## 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\_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`) |
***
## 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\_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
Agent Analytics requires a connected data source (Cloudflare Workers or a CSV/CLF log upload). See [Crawl Insights](/crawl-insights) for setup.
***
## 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. |
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.
***
## 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\_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. |
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."
***
## 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.
All write tools require organization-owner access and a `project_id`. 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.
## create\_brand
Create a new tracked brand in a project (own brand or competitor).
| Parameter | Type | Required | Description |
| ------------ | --------- | -------- | ------------------------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `name` | string | Yes | Brand name |
| `domains` | string\[] | No | Domains associated with the brand |
| `aliases` | string\[] | No | Alternate names the brand should be matched under |
| `regex` | string | No | Optional regex pattern for brand mentions in chat text |
| `color` | string | No | Hex color used for the brand in charts (e.g. `#1A2B3C`) |
**Returns:** `{ id }`. The created brand ID.
***
## update\_brand
Update a brand's name, regex, aliases, domains, or color. Changes to name, regex, or aliases trigger a background metric recalculation. Further edits during the recalc will fail; wait a few minutes and retry. Color changes don't trigger recalculation.
| Parameter | Type | Required | Description |
| ------------ | -------------- | -------- | -------------------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `brand_id` | string | Yes | The brand ID to update |
| `name` | string | No | New brand name |
| `domains` | string\[] | No | New domain list (replaces existing) |
| `aliases` | string\[] | No | New alias list (replaces existing) |
| `regex` | string \| null | No | New regex. Pass `null` to clear an existing regex. |
| `color` | string | No | New hex color (e.g. `#1A2B3C`) |
**Returns:** `{ success: true }`.
***
## delete\_brand
Soft-delete a brand. **Destructive.**
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------- |
| `project_id` | string | Yes | The project ID |
| `brand_id` | string | Yes | The brand ID to delete |
**Returns:** `{ success: true }`.
***
## 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 accepting the same fields as [`create_brand`](#create-brand): `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\_prompt
Create a new prompt in a project. May consume plan credits.
| Parameter | Type | Required | Description |
| -------------- | --------- | -------- | ------------------------------------------------------------ |
| `project_id` | string | Yes | The project ID |
| `text` | string | Yes | The prompt text |
| `country_code` | string | Yes | ISO 3166-1 alpha-2 code the prompt targets (e.g. `US`, `DE`) |
| `topic_id` | string | No | Topic ID to attach the prompt to |
| `tag_ids` | string\[] | No | Tag IDs to attach to the prompt |
**Returns:** `{ id }`. The created prompt ID.
***
## update\_prompt
Update a prompt's topic and/or tags. `tag_ids` fully replaces the existing tag set. Pass `topic_id: null` to detach the prompt from its topic.
| Parameter | Type | Required | Description |
| ------------ | -------------- | -------- | --------------------------------- |
| `project_id` | string | Yes | The project ID |
| `prompt_id` | string | Yes | The prompt ID to update |
| `topic_id` | string \| null | No | New topic ID, or `null` to detach |
| `tag_ids` | string\[] | No | New tag set (replaces existing) |
**Returns:** `{ success: true }`.
***
## delete\_prompt
Soft-delete a prompt. **Destructive.** Cascades to the prompt's chats, which are soft-deleted too.
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | ----------------------- |
| `project_id` | string | Yes | The project ID |
| `prompt_id` | string | Yes | The prompt ID to delete |
**Returns:** `{ success: true }`.
***
## 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 accepting the same fields as [`create_prompt`](#create-prompt): `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\_prompt
Archive a prompt (sets `is_archived = true`) so it stops running while its chats and history stay intact. Use this instead of [`delete_prompt`](#delete-prompt) when the data should be retained.
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | ------------------------ |
| `project_id` | string | Yes | The project ID |
| `prompt_id` | string | Yes | The prompt ID to archive |
**Returns:** `{ success: true }`.
***
## unarchive\_prompt
Unarchive a prompt (sets `is_archived = false`), reactivating it so it resumes running. Subject to the project's active-prompt plan limit.
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | -------------------------- |
| `project_id` | string | Yes | The project ID |
| `prompt_id` | string | Yes | The prompt ID to unarchive |
**Returns:** `{ success: true }`.
***
## create\_tag
Create a new tag. Tags are cross-cutting labels that can be attached to prompts.
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `name` | string | Yes | Tag name |
| `color` | string | No | Tag color (from Peec's color palette) |
| `group` | string | No | Optional tag group; grouped tags share the group's color, so `color` is ignored when a group is set |
**Returns:** `{ id }`. The created tag ID.
***
## update\_tag
Update a tag's name, color, or group.
| Parameter | Type | Required | Description |
| ------------ | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `project_id` | string | Yes | The project ID |
| `tag_id` | string | Yes | The tag ID to update |
| `name` | string | No | New tag name |
| `color` | string | No | New tag color |
| `group` | string \| null | No | Move the tag into a group (it inherits the group's color), `null` to ungroup, or omit to leave the group unchanged |
**Returns:** `{ success: true }`.
***
## delete\_tag
Soft-delete a tag and detach it from every prompt it's attached to. **Destructive.**
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | -------------------- |
| `project_id` | string | Yes | The project ID |
| `tag_id` | string | Yes | The tag ID to delete |
**Returns:** `{ success: true }`.
***
## 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 accepting the same fields as [`create_tag`](#create-tag): `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\_group
Rename and/or recolor a user-defined tag group. The change applies to every tag in the group. Provide a new `name`, a new `color`, or both.
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | ------------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `group` | string | Yes | The current group name |
| `name` | string | No | New group name to rename to |
| `color` | string | No | New color applied to every tag in the group |
**Returns:** `{ tag_count }`. The number of tags affected.
***
## delete\_tag\_group
Delete a user-defined tag group. **Destructive.** By default its tags are kept and ungrouped; set `delete_tags: true` to delete the tags themselves and detach them from every prompt.
| Parameter | Type | Required | Description |
| ------------- | ------- | -------- | ------------------------------------------------------------------------ |
| `project_id` | string | Yes | The project ID |
| `group` | string | Yes | The group name to delete |
| `delete_tags` | boolean | No | Delete the group's tags instead of just ungrouping them (default: false) |
**Returns:** `{ tag_count }`. The number of tags affected.
***
## create\_topic
Create a new topic. Topics group related prompts.
| Parameter | Type | Required | Description |
| -------------- | ------ | -------- | ---------------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `name` | string | Yes | Topic name (1–64 characters) |
| `country_code` | string | No | Optional ISO 3166-1 alpha-2 code for the topic |
**Returns:** `{ id }`. The created topic ID.
***
## update\_topic
Rename a topic.
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | -------------------------------- |
| `project_id` | string | Yes | The project ID |
| `topic_id` | string | Yes | The topic ID to update |
| `name` | string | No | New topic name (1–64 characters) |
**Returns:** `{ success: true }`.
***
## delete\_topic
Soft-delete a topic. **Destructive.** Associated prompts are detached (not deleted); any AI-generated prompt suggestions under the topic are deleted.
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------- |
| `project_id` | string | Yes | The project ID |
| `topic_id` | string | Yes | The topic ID to delete |
**Returns:** `{ success: true }`.
***
## 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 accepting the same fields as [`create_topic`](#create-topic): `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.
***
## 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 }`.
***
## 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 }`.
***
# 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"*
Include a time range in your questions. *"Last 30 days"*, *"this month"*, or *"past week"* gets you better results.
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.
## 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
> *"Break down our brand visibility by AI model for the past two weeks."*
Get an overview of your performance for each AI model.
> *"Which topics have the highest and lowest visibility for our brand?"*
Identify the strengths and weaknesses in your AI search presence.
### Competitive analysis
> *"Compare our share of voice against all competitors for the last month."*
Your mention share vs the competitive set.
> *"How does our sentiment compare to \[competitor name] on ChatGPT?"*
Find out how positively AI models describe you vs a specific competitor.
> *"Which competitor is mentioned first most often across all AI models?"*
Understand who consistently wins the top position in AI responses.
### Sources and citations
> *"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.
> *"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.
> *"Which competitor domains have the highest citation rate?"*
Find out which competitor websites AI treats as authoritative.
> *"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.
### Reporting
> *"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.
> *"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.
> *"Which topics have high competitor visibility but low visibility for our brand?"*
Find opportunities where competitors are visible, but you're not.
### Actions and next steps
> *"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.
> *"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).
### 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.
> *"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.
> *"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.
> *"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.
> *"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.
> *"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.
### 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`).
> *"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.
> *"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.
> *"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.
> *"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.
### Edit your project setup
> *"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`.
> *"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.
> *"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.
> *"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.
> *"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.
> *"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.
### Workflows validated in the MCP Challenge
> *"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.
> *"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.
> *"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.
> *"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.
## 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
Understanding all the key metrics that drive your AI search optimization strategy.
Here are the main metrics Peec AI tracks and what they mean.
## 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. 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:** Average ranking when your brand appears in AI responses (lower numbers are better). Shows where you rank compared to competitors when mentioned. Position 1 means you're 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:**
* **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.
* **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.
* **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.
## Brand visibility vs source visibility
Understanding the difference between these two is important:
* **Brand visibility:** Your brand 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 visible as a brand. And you can be mentioned as a brand without your website being used.
Peec AI tracks both so you can spot 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 name with a topic, but not trust your content as a reference.
# Position
Source: https://docs.peec.ai/metrics/brand-metrics/position
How your brand ranks in AI responses.
## Overview
Position measures the average ranking of your brand in AI responses (e.g., mentioned first, second, etc.).
Being mentioned first or early in responses indicates higher brand authority and relevance for the topic being discussed.
## How position is measured
When AI models generate responses, they often mention multiple brands or sources. Your position score reflects where your brand typically appears in these mentions:
The position metric calculates the average ranking across all responses where your brand appears.
![Peec AI GEO Metrics 1 Pn]()
## Why position matters
### Brand authority
A higher 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 a competitive 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
Learn how the tone of your brand mentions affects your overall performance.
Understand how often your brand is mentioned in AI responses.
# Sentiment
Source: https://docs.peec.ai/metrics/brand-metrics/sentiment
The tone and sentiment of your brand mentions.
## Overview
Sentiment measures the overall tone of AI responses when mentioning your brand on a scale from 0 to 100. This metric helps you understand how AI models perceive and describe your brand.
Most sentiment scores fall between 65 and 85, with higher scores indicating more positive language and associations.
## 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.
![Peec AI GEO Metrics 2 Pn]()
## 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
Learn how your brand's ranking position affects overall performance
Understand how often your brand is mentioned in AI responses
# Share of Voice
Source: https://docs.peec.ai/metrics/brand-metrics/share-of-voice
How much of the conversation you own.
## Overview
Higher SoV means you are more influential than other brands when AI chats mention a brand, even if your visibility differs.
Share of Voice measures the percentage of your brand mentions in AI responses compared to all brands mentioned, including yours. This indicates the share of influence you have whenever AI models mention your tracked brands.
**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**.
![Peec AI Share of Voice]()
## 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
Understand how often your brand is mentioned in AI responses.
Learn how the tone of your brand mentions affects your overall performance.
# Visibility
Source: https://docs.peec.ai/metrics/brand-metrics/visibility
How often your brand is mentioned in AI responses.
## Overview
The Visibility Score measures the percentage of AI responses that mention your brand. This metric indicates how frequently AI models recognize and reference your brand when discussing relevant topics.
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.
## How 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.
![Peec AI GEO Metrics 3 Pn]()
You can also filter by daily, weekly, or monthly, and choose the type of graph you want to display, either a line or a bar chart.
You can simply use the buttons at each corner of the graph to adjust it as desired.
## Why visibility score matters
### Brand recognition
Visibility score directly 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
Understand how influential your brand is across chats compared to the other tracked brands
Learn how your brand's ranking position affects overall performance
Understand how the tone of your brand mentions affects your overall performance
# Organizing your setup
Source: https://docs.peec.ai/organizing-your-setup
Keep your prompts manageable and analysis-ready with smart organization.
[Watch "Organizing your setup" on YouTube](https://youtu.be/_9Z43OpAumM)
As your prompt collection grows, you need systematic ways to handle them at scale. Prompts operate at different levels — active, archived, and deleted — each serving different purposes.
Breaking prompts into organized chunks becomes essential because these groupings form the foundation of your analysis. Effective organization means you can quickly compare performance across categories instead of drowning in hundreds of individual prompt results.
## Manage your prompts
We’ve made it easy for you to manage prompts with batch actions.
Different ways you can select multiple prompts:
* Click the checkboxes next to individual prompts.
* Hold the shift key and click on another checkbox to select multiple at once.
* Tick the checkbox in the top row to select all prompts on the page.
Use search to filter prompts before selecting for easier bulk actions.
In each tab, you’ll find these available batch actions:
From the **Active** tab:
* **Assign Tags:** Add tags to multiple prompts simultaneously.
* **Assign Topics:** Move prompts to different topics (one topic per prompt).
* **Archive:** Archive multiple prompts while still preserving data.
From the **Archived** tab:
* **Assign Tags and Topics:** Same as above.
* **Activate:** Restore prompts to active status.
* **Delete:** Permanently remove prompts and all associated data. Only use if necessary.
Understanding prompt states:
* **Active:** We run the prompt against AI models once a day and include it in analytics.
* **Archived:** We don’t run it anymore, but keep all chat history and sources in analytics.
* **Deleted:** We remove everything associated with that prompt and treat it as if it never existed.
## 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 generate better prompt suggestions based on your chosen topics.
### Understanding tags vs topics
**Tags:** Tags are dimensions you can use to slice and dice 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”)
You can refer to our Helper Article "[Part 2: Using tags effectively](https://help.peec.ai/en/articles/12591123-part-2-using-tags-effectively)" for some best practices
**Topics:**
Each prompt can belong to only one topic. For example: “CRM Software,” “Email Marketing Tools,” “Project Management.”
You can easily create new topics by clicking on the **"Add Topic"** button on the left side of the prompt table.
Topics help you categorize your prompts and provide a folder-like structure for easy navigation and organization. They are also useful when tracking hundreds of prompts, giving you a quick overview of what is your brand's visibility for any given topic.
When you view your prompts, you’ll see them grouped by topics. Each prompt within that topic might have several tags (or no tags). Prompts without topics show under the **No Topic** folder.
By using topics, you can:
* Track visibility at the topic level.
* Generate new prompt variations based on topics.
* Filter and segment prompts more effectively.
TLDR: **Tags** vs **Topics**
* **Tags:** Multiple per prompt, flexible filtering (like Gmail labels).
* **Topics:** One per prompt, visual folders (like file folders).
### **Branded and Intent classification tags**
Alongside the tags you create yourself, Peec automatically assigns two special classifications to every prompt: **Branding** and **Intent Type**. These appear as dedicated columns on your prompts table and are assigned by Peec in the background when a prompt is created. You do not need to set them yourself.
![System Tags]()
**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 any competitor directly. (E.g., "What is HubSpot?" or "HubSpot pricing.")
* **Non-branded:** The prompt is a generic question with no explicit brand mention. (E.g., "best CRM software" or "how to manage customer relationships.")
**Intent Type** tells you the purpose behind the prompt:
* **Informational:** The user wants to understand something. (E.g., "what is CRM software" or "how does email marketing work.")
* **Commercial:** The user is comparing options. (E.g., "best project management tools" or "HubSpot vs Salesforce.")
* **Transactional:** The user is close to a decision. (E.g., "HubSpot pricing" or "buy CRM software.")
You can filter your entire prompts table by Branding or Intent Type using the dedicated filters at the top of the page. Both are single-select. You can combine them with your own tag and topic filters for more precise views.
You can use these tags to identify gaps, opportunities, and other relevant insights about your data.
* **For example:** filter for **non-branded + commercial** prompts to find topics where you have a visibility opportunity but no direct brand pull.
Branded and Intent classifications are separate from the tags you create yourself. They cannot be renamed, but they can be reclassified on a prompt basis. Each prompt gets exactly one value per group. If a prompt shows no value in either column, classification is still running and fills in automatically within a short time.
## **Rearrange metrics on your prompts table**
Tables in Peec can be customized and sorted by nearly any available metric. In your prompts, you will find multiple metrics that you can add to the table you are interested in.
You can choose which items to show or hide in your table. You can also rearrange the table so your most relevant metrics always appear first.
To return to your previous view, open the table settings and click **Reset to default view**.
Besides your usual metrics, you can also see:
* **Shopping:** The percentage of chats that have triggered a shopping carousel
* **Product Comparison:** The percentage of chats where AI compares multiple products
* **Images:** The percentage of chats that include an image
* **Ads:** The percentage of chats that have triggered an Ad
* **Map:** Percentage of chats that have displayed a map within the answers
* **Web Search:** The percentage of chats that have actually triggered a web search
Please note that these metrics (in comparison to your main ones like Visibility, SoV, Position, and Sentiment) are independent of whether your brand is mentioned.
# Shopping overview
Source: https://docs.peec.ai/overview
Track how your products appear across AI models by product, competitor, and week.
## Get started with AI Shopping
Head to **Shopping** in the sidebar and upload your products to get started. Once your catalog is live, the **Products** table becomes your command center for understanding visibility, rankings, and competitive performance across AI recommendations.
[Watch "🛒 AI Shopping Analytics: Track How ChatGPT Recommends Your Products | Peec AI" on YouTube](https://youtu.be/yhWL-GoqxKs)
When someone asks an AI model for a product recommendation, it returns a shortlist. AI Shopping shows you whether your products make that shortlist, where they rank, and which competitors appear alongside them, so you can understand where you are winning, and where you might be losing.
It works at the product level, not just the brand level. Upload your catalog, and Peec AI matches your products to the conversations it already tracks. You get visibility, rankings, and competitor insights for every product, all 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 helps you understand how your products appear in AI answers and how they perform against competitors.
## Overview dashboard
![Screenshot 2026 06 16 At 10 39 38]()
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 are showing up most often in AI shopping answers, and where does my brand rank?”
In the Overview dashboard page, you will be able to see:
* **Overview graph (Brands / Products):** Shows the visibility, position, SoV, and Win Rate of your brand and competitors over time.
* You can toggle between “Brands” and “Products” on the right to view visibility for each. (If you select products, SoV will not be available.)
* **Top 7 Brands / Products:** Quick overview of the top 7 brands (or products) that are ranking in AI shopping.
* **Performance by visibility:** Shows the products that appear the most in AI answers versus the least ones.
* **Shopping queries:** Aggregated across all the prompts you’re viewing, these are the queries driving shopping answers. Peec 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. Fan-outs shape the text around the carousel, and shopping queries decide which products fill it.
**Shopping queries** overlap heavily with Google Shopping search, so they double as a feed for your wider search and merchandising work.
## 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
Every product in your catalog with its AI Shopping metrics, plus the per-product detail view for visibility, competitors, and attributes.
Here, you can see detailed product-level insights, understand how products perform, view how they are grouped within the categories you’ve set up, and access your full uploaded catalog.
## Product Table
![Screenshot 2026 06 16 At 09 00 08]()
The Products table is where the underlying signal appears. Each row represents a product in your catalog, along with the metrics Peec aggregates from the chats it tracks. Start here to understand what AI Shopping measures.
In the table, you will see the following 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 fan-out 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. |
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.
### Attributes
When ChatGPT compares products, it builds a table of attributes based on the user’s question and the context available to it. Peec captures those attributes and tracks how often each one appears across your chats.
You can use this to:
* **Optimize your product detail pages:** If the AI consistently evaluates products based on attributes you don’t mention on your own pages, it has less information to work with when deciding whether to recommend you.
* **Cover the attributes that matter:** By covering the attributes that matter most, you make it easier for the model to choose your product. For the full breakdown, see how each attribute is scored against competitors in the detail view.
## Product detail page
![Screenshot 2026 06 16 At 09 02 06]()
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. You’ll see more detailed, product-specific information, giving you deeper insight into what is happening with 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.
* **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 to the previous period of the same length.
Use the filters at the top to analyze more granularly.
As you scroll, you will find different graphs, each one telling a different story:
* **Co-featured products:** The products ChatGPT recommends alongside this one. This is your real competitive set at the product level, not just the brand level. It tells you which specific products you’re being compared against in the same answer.
* **Position versus competitors:** A box plot of where this product ranks against the products it competes with, sorted by visibility. The plot shows more than the median position. It shows the variance and the outliers, too.
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.
* **Shopping queries:** Total number of shopping searches for the selected timeframe. (Product carousels are built from Google Shopping category searches rather than web searches, making these queries the most important factor in improving your product’s visibility in carousels.)
* **Fan-out 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, fan-out queries influence the content and context surrounding them.)
### 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
## What is the Brand Profile?
When you connect a domain to Peec, the platform automatically extracts key information about your business. Things like your company name, what you do, who your target audience is, and what products or services you offer. This extracted data is your **Brand Profile**, which serves as the foundation for everything Peec generates: topics, prompts, and brand suggestions.
![Project Profile]()
The Brand Profile surfaces in two places:
* **During onboarding:** After connecting your domain, there is a dedicated "Your brand profile" step before you reach Topics. This is your first chance to review what Peec extracted and make sure it's right.
* **Under project:** Once you're up and running, you can return to the profile at any time under the project section in the side panel. Any changes you save will trigger a refresh of your topic and prompt suggestions.
Your brand profile includes the following fields:
* **Company name:** The name Peec will use to identify your brand across all features
* **What you do:** A short description of your core business or product
* **Market segment:** The industry or vertical you operate in
* **Brand identity:** How you position yourself (e.g. premium, challenger, enterprise)
* **Target audience:** Who your customers are
* **Products / services:** The specific offerings you want tracked and surfaced in AI answers
## Why it matters
Using the brand profile can help you get better, more prompt recommendations, making it easier to understand which prompts might be relevant for tracking as they become more tailored to your audience, industry, and offerings.
Once you’ve updated your brand profile, return to your suggested prompts and click **Suggest more** prompts to generate new ones tailored to your updated settings. Review them and select the prompts most relevant to tracking.
![Suggesting New Prompts]()
By making the profile visible and editable, Peec gives you direct control over the inputs that shape your entire experience.
Accurate profile = better topics = more relevant prompts = more actionable insights.
# Quickstart Guide
Source: https://docs.peec.ai/quickstart-guide
The fastest way to understand your brand’s AI search presence.
[Watch "Peec AI Product Walkthrough" on YouTube](https://youtu.be/CT4aKlOouFQ)
This quickstart guide gets you set up fast so you can dive deeper into the platform with solid data foundation. It takes less than 10 minutes to complete these steps, and you'll have your first AI visibility insights within 24–48 hours.
## Step 1: Setting up your prompts
Prompts are the questions you want to be found for in AI search. We run them daily across AI platforms like ChatGPT and Perplexity to see who gets mentioned.
**Your task:** Add your first 10 prompts.
We suggest prompts based on your brand and website (check the **Suggested** tab on the **Prompts** page and use **Topics** to get better suggestions), or manually add your own using the **Add** button.
**Quick tip:** Ask yourself "What do I want my brand to be found for?" Take your Google Search Console keywords and rephrase them conversationally.
**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?"
Don't worry about getting them perfect — you can always change them later.
## Step 2: Identifying your competitors
While your prompts run, we detect competitor brands mentioned in AI responses and suggest them for you.
**Your task:** Add 3–4 competitors.
Navigate to **Brands** and either:
* Accept suggested competitors (we auto-detect brands from your prompt responses).
* Use **+ Add Competitors** to manually add your own.
This shows you who appears alongside (or instead of) you in AI responses and how often they're mentioned compared to your brand.
**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).
## Step 3: Understanding your dashboard
Your **Overview** dashboard shows three key areas once your prompts start running (within 24-48 hours):
**Your task:** Navigate to **Overview**.
Here you can see:
1. **Visibility graph:** Percentage of chats mentioning each brand over time.
2. **Brands:** Where you stand with visibility, sentiment, and position scores compared to competitors.
3. **Top sources:** Which websites AI platforms reference across your prompts (split by source types and domains).
4. **Recent chats:** Latest AI responses (toggle to see chats with all your tracked brands or just yours).
This shows you exactly where you stand in AI search and how you compare to competitors across all your tracked prompts.
You can use filters at the top of your dashboard to filter by AI models, date range, or specific competitors to focus your analysis.
## Step 4: Understanding your sources
When AI platforms search the web for answers, we capture those sources. They're 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).
Quick opportunities to spot:
* 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.
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.
## What’s next?
Now that you've got the basics set up, here are two great next steps:
* **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.
# 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 show you what your prompts ask about: the prompts you track decide which products, competitors, and buying intents you get signals on.
This guide explains how to build that prompt set. It's written for brands that sell their own products; multi-brand retailers and marketplaces work differently and aren't covered here.
If you're new to Peec AI, we recommend reading [**"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) first.
Two kinds of prompts come up throughout this guide:
* A **category prompt:** This asks about a type of product (e.g., *"best running shoes for beginners"*. It measures every product you sell in that category at once.)
* A **product prompt** names one specific product (e.g., *"Is the Nike Pegasus good for flat feet?"*. It gives you a close-up on that one product.)
## Step 1: Starting with categories
Every product in your catalog is tracked automatically. Peec AI matches each product to the category prompts it's relevant to, so *"best running shoes for beginners"* measures every running shoe you sell, not just one.
You don't need a prompt for **every** product. Peec AI matches each product to the category prompts it's relevant to, so *"best running shoes for beginners"* measures every running shoe you sell, not just one.
This is why you don't need a prompt for every product. A single-category prompt already covers all products in that category.
Categories are the backbone of an effective shopping prompt set for two reasons:
1. Every product is measured through its category's prompts regardless of how they're worded.
2. A clean category structure mirrors how you already organize your range, so the data stays readable. Build the set around the intents you want to track, with categories as the frame.
## Step 2: Build each category's core set
For each category, start with a small core of reliable prompts. Lead with non-branded discovery, then add a smaller branded slice.
**Non-branded discovery** (the priority)**:** These carry most of the day-to-day value, because they test whether AI recommends you when the shopper hasn't named a brand:
* *"What's the best \[product category] for \[key use case]?"* The broad recommendation question category leaders should win. A few variations on the use cases and constraints that matter most in that category (see Step 3).
**Branded slice** (minority)**:** A small number of prompts that name your brand. They're useful, but branded prompts almost always show you, so they inflate visibility if they dominate. Hold them to roughly 15-20% of the set:
Peec auto-classifies them under the branded tag, so you can filter to non-branded any time to read your true discovery numbers, no separate project needed.
* *"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:** On top of the category core, add product prompts where the close-up is worth it:
* **Small catalogs** (up to about 100 products): around 3 prompts per product is workable, folded into the category structure.
* **Hero products:** Focus product prompts on your highest-priority products, with comparisons and purchase questions.
* **The long tail:** Track a handful of product prompts for non-hero products too, grouped under a single tag, so you can see how they perform without crowding the set.
**On large catalogs, skip the one-prompt-per-product approach.** Because every product is already matched to the category prompts above, a separate prompt for each one mostly repeats coverage you already have. Add product-specific prompts only for your hero products.
On large catalogs, don't try to cover every product with its own prompt, because each product is already matched to its category prompts. A prompt per product mostly repeats coverage you already have.
## 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 a set, multiply the dimensions:
```text theme={null}
coverage = categories × buyer contexts × intent stages
```
This should be your starting floor, giving you a baseline from which you can build and grow. Every distinct buying situation you add (a new buyer context, competitor, market, or category) is another prompt worth tracking, with no upper limit as long as each one is a genuine buying situation.
If there is room to increase the number of prompts being tracked, use it to expand into more buying situations, use cases, competitor comparisons, and markets.
To ensure this framework works, you can follow these rules:
* **Prioritize distinct buying situations:** A new intent or context adds more than a reworded duplicate. That said, tracking a few variants of your most important prompts is worthwhile: it stabilizes the day-to-day numbers, since a single prompt on a single day is noisy, whereas a handful read steadily.
* **Name something shoppable in every prompt**: A product category or a specific product, not just a vague need (e.g., *"Best Pilates socks for beginners"* triggers shopping results, while *"what do I need for my first Pilates class?"* usually doesn't).
* **Prompts with commercial intent:** Shopping recommendations appear on more than half of commercial prompts, versus roughly one in ten informational ones. Keep some informational coverage, but focus the set on discovery and purchase decisions.
Not every prompt will generate a shopping recommendation, and that's normal. Shopping results are most likely for clear product-focused queries, especially physical goods rather than services.
# 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.
[Watch "Setting up your prompts" on YouTube](https://youtu.be/wcbmAs4Q-oE)
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 to understand how AI models work, create effective prompts and questions, organize systematically with topics and tags, and handle prompts at scale using our suggestion engine.
By the end of it, you’ll build a comprehensive 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:
1. **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)
2. **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”
3. **Response generation:** Crafting an answer that matches both intent and context.
Different intents lead to different responses, but similar intents produce consistent results over time, even when worded differently.
For example:
* “What’s the best CRM?” vs “What’s the best email tool?” → Different intents → Different responses.
* “What’s the best CRM?” vs “Which CRM should I choose?” → Same intent, different wording → Similar responses.
This means you don’t need multiple variations of the same question. AI models recognize similar intents regardless of exact wording.
**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).
What this means for your tracking:
* **Exact wording 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.
### The anatomy of an effective prompt
Every prompt contains two key components that determine how AI models respond:
1. **Intent:** The main ask.
2. **Context:** The specifics.
The intent is the core request — what you want the AI to do or answer. This drives the response. Examples of clear intent:
* "What's the best..." (seeking recommendations)
* "How do I..." (seeking instructions)
* "Compare..." (seeking analysis)
Context provides constraints or situation details that shape how the AI fulfills the intent. Types of context:
* **Audience:** "for small businesses," "for beginners"
* **Use case:** "for remote teams," "for e-commerce"
* **Constraints:** "under \$100," "with less than 50 employees"
**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).
What this means for your tracking:
* **Exact wording 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 like "what tools should I use" or "which platforms work best" to get brand mentions in your tracking.
## Prepare your topics
Think in clusters of related prompts rather than individual questions for better suggestions and organization.
Before diving into individual prompt creation, consider organizing your tracking around topics. Topics help you think systematically about the different areas where you want visibility, and they unlock better prompt suggestions from our AI engine.
When you create topics first, Peec AI can generate more targeted prompt suggestions based on those specific themes. Instead of generic suggestions, you'll get prompts tailored to your exact focus areas.
### 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 tool.
* “Security” — prompts comparing fraud protection, security features, and safety measures across financial services.
### Setting up your first topics
![Topics 2]()
Start with 3–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 always create additional topics later, but starting with topic-based thinking helps you build a more organized and effective prompt strategy from day one.
Topics also make analysis easier down the line — you can track visibility at the topic level instead of individual prompts.
## Create your prompts
There are three ways to add prompts to your project, depending on your workflow and scale.
Navigate to **Prompts** in your sidebar to get started.
### Option 1: Use prompt suggestions
![Prompt Suggestion]()
Our suggestion engine creates prompts based on your website, industry context, and existing prompts in your project.
How it works:
* Go to the **Suggested** tab in the Prompts section, and review generated suggestions.
* Click **Track** to move prompts to your **Active** tab.
* If you don't see suggestions, click **Suggest** **prompts** to create new ones.
Click **Suggest more** to generate more suggestions. If you’ve reached the limit of suggested prompts, reject a few unsuitable ones and click the button again.
**You can also get suggestions per topic:** Simply create a new topic using the "Add Topic +" button, and then navigate to the "Suggested" tab. Click on the topic you just created and accept or reject prompts using the buttons on the right.
To get great prompt suggestions, make sure you have set up a good [brand profile](https://docs.peec.ai/project-profile)
Accepted prompts are added to your Active prompts and start running immediately, joining the regular 24-hour cycle.
### Option 2: Add prompts manually
![Add Prompts Manually Gi]()
Add prompts individually or in batches using the manual input method.
* Click **Add Prompt** in the top-right of the Prompts page.
* Enter your prompt or enter multiple prompts using line breaks (one prompt per line).
* Set **Location** to choose which country to run the prompt from.
* Add **Topic** and/or **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).
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.
### Option 3: Bulk CSV upload
![Bulk Csv Upload Gi]()
Upload multiple prompts at once using a structured CSV file.
How to upload:
* Click **Add Prompt** and select **Bulk Upload.**
* Drag and drop your CSV file or click to browse.
* Confirm the preview matches your desired structure.
* Imported prompts appear in **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 with 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, etc.).
* If blank or invalid, your project's default location is used.
* **Column 3:** Add a topic (E.g., CRM Software)
* **Column 4+:** Tags to assign to each prompt:
* Add text to assign as many tags as you need.
* Use one column per tag for best organization.
You can [download this example CSV file](https://app.peec.ai/Peec%20CSV%20Template.csv?comet_token_override=2476806873274882222916434821686594529691322837919) or this [Google Sheets template](https://docs.google.com/spreadsheets/d/1VgBaBqAesMpDoRtGc_zAntDtUEE8ZjXxdM3ME3-PAYo/edit?usp=sharing) to get started quickly.
Please make sure your CSV file is UTF-8 encoded.
## Use prompt volume
[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.
Prompt Volume helps you find high-impact topics by measuring genuine search interest, ensuring your content meets a real need.
### 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.
* **Keywords 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.
Our model uses all these data points to identify the core themes in your prompts. It then matches them to what people are already searching for. The result is a clear, industry-relative score that shows the true demand for your content.
### Understanding your scores
Your Prompt Volume score ranges 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 your **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 deactivating less important ones rather than deleting them entirely.
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).
# Sidebar navigation
Source: https://docs.peec.ai/sidebar-navigation
Quick reference to all navigation sections and their key features.
Here's what you'll find in your Peec AI sidebar, along with what each section does.
## General
* **Overview:** Your main dashboard shows competitive performance, tracked brands with the highest visibility, top sources, and recent AI responses across all prompts. Use filters to focus on specific timeframes, models, or topics.
* **Prompts:** Create and manage the questions you use to test AI platforms. Set up prompts individually or in bulk, organize with tags and topics, and monitor their performance over time.
## Sources
* **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.
* **Gap analysis:** Quickly identify the domains and URLs where your competitors are being mentioned, but your brand is not.
## 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?
## 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 competitor's. (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").
## Actions
Get tailored insights and recommendations broken down by “On-page” and “Off-page” about what kind of content you can leverage to strengthen your brand's visibility.
* **Earned (Off-page):** See insights and recommendations to increase your brand presence on third-party sites.
* **Owned (On-page):** Get recommendations and actionable steps for your own content and website.
## 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.
* **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).
* **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.
## Refer & Earn
Access your personal referral link to share with clients or other users to earn a commission. You can earn up to \$1,000, and the referred can receive 30% off on their first month for their subscription.
You can share this via different channels such as Email, LinkedIn, WhatsApp, and Slack, and track your performance and earned commissions.
## 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.
# Understanding chats
Source: https://docs.peec.ai/understanding-chats
Learn how to read the AI responses that form the foundation of all your analytics.
[Watch "Understanding chats" on YouTube](https://youtu.be/EnxfmarTlrg)
Chats are the AI-generated responses we produce by running your prompts daily across different platforms. Understanding chat anatomy is crucial 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
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 we analyze to generate your metrics and insights:
* **Status:** Shows if the prompt ran successfully.
* **Model:** Which AI platform generated the response (ChatGPT, Claude, Perplexity, etc.).
* **Location:** Geographic location we prompted from (e.g., United States).
* **Sentiment**: How the AI model talks about your brand — positively, neutrally, or negatively (measured as a score between 0–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.
* **Fanout Queries:** 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.
![Image (7)]()
For Gemini chats, we can only prompt from the United States for now. That’s why you won’t see a location indicator for Gemini responses.
## 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. These appear as direct mentions in-line in the response body. Citations indicate the AI used specific information from that URL to create particular sentences or sections.
* **Sources:** All URLs the AI model accessed during response generation. 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 if not directly cited in the response.
Example: An AI response might cite 5 sources directly in the text but show 8 sources in the sidebar. All 8 contributed to the response, but only 5 were explicitly referenced.
When a URL is cited multiple times, it will appear 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 require different optimization strategies. Track both metrics to get the complete picture of your performance.
## 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 ChatGPT doesn’t search the web, you’ll see responses with no sources listed. This is normal behavior, not a data issue.
* **Perplexity:** Shows many sources in the sidebar but tends to cite fewer of them directly in the response text. You’ll often see higher source counts but lower citation numbers.
* **Claude and other models:** Each has unique patterns for how they search, cite, and reference sources.
AI models have inherent randomness in source selection. A source might appear one day and be completely absent the next. Focus on trends over weeks rather than daily changes.
## Reading chat position rankings
When multiple brands appear in a chat, we calculate position based on mention order — including all detected brands, not just your tracked competitors.
**Example:** If a chat mentions Hyundai (1st), Chevrolet (2nd), BMW (3rd), BMW ranks in position 3. If tomorrow’s chat mentions Hyundai, Chevrolet, Ferrari, BMW — even though you haven’t added Ferrari as a competitor, BMW’s position becomes 4th.A higher 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 a true competitive context by showing where you rank among all the mentioned brands, not just your selected competitors.
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.
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.
## 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 runs a prompt, the AI model's response can contain more than just text. It might serve a sponsored ad, pull up a local business map, or run a live web search before answering. These extras are what we call **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 maps means the AI is treating it as a local discovery query.
### Available features
Each chat can carry any combination of the following features:
* **Ads:** The AI model included a sponsored placement in the response. Relevant for understanding monetization pressure on your topics.
* **Maps:** The AI returned a local business map result. Common for location-based or "near me" style queries.
* **Web search:** The AI performed a live web search to generate the response, rather than answering from memory.
* **Shopping:** The AI included product or shopping results
* **Product Comparison:** Chats in which the AI makes comparisons between two or more brands
### Where to find features
Features appear across the platform in two places:
* **All Chats table:** Each chat row displays its features as visual flags. Use the dropdown filter at the top of the table to show only chats matching specific feature types (e.g., only chats that included ads, or only chats where web search was used)
* **Prompts and Topics tables**: Each prompt and topic now 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.
![Chat Features]()
### 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.
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.
# Understanding sources
Source: https://docs.peec.ai/understanding-sources
Discover which websites AI models trust and learn how to optimize your presence across them.
[Watch "Understanding your sources" on YouTube](https://youtu.be/OOh0SVkKN4w)
Sources are the foundation of AI optimization. While you can’t directly influence AI responses or training data, you can influence the sources AI models reference. Understanding the sources that are being used by the AI models can help identify which websites and pages are building your brand’s authority and which ones are helping your competitors.
## Why sources matter
Optimizing sources gives you the most control over your AI visibility. Sources are all URLs AI models access during response generation, while citations are sources explicitly referenced in the response text. Both contribute to AI responses.
You have full control over your own website content and can influence external sources through PR, partnerships, and community engagement. When AI models reference sources where you have a stronger presence, your visibility increases.
**Important limitation:** AI models only see HTML content. They can’t read behind paywalls or load JavaScript-dependent content.
Under the sources section, you will find the **Domains** and **URLs** pages. Check both of them to gain insights into the multiple kinds of content that AI models are using constantly as sources to answer the prompts you are tracking. Use this information to reverse-engineer what's working well for your competitors and other domains, identifying potential websites where you could boost your visibility through partnerships and collaborations.
## Gap Analysis
You can use the Gap Analysis function on either the Domains or URLs pages to show the sources where your competitors are mentioned, but your brand is not, helping you discover content gaps and partnership opportunities you might otherwise miss.
Use this tool to identify those gaps to work on your content strategy
How to prioritize opportunities:
* **Start with high Gap Scores:** Focus on sources that are both frequently used and mention multiple competitors.
* **Check URL details:** Click on any URL to see how that page has been used by LLMs over time, and which prompts consistently trigger it as a source and cite it.
* **Action by domain type:** Editorial sites may require PR outreach, whereas UGC platforms may allow direct community engagement.
## How to use Source insights
Different source types require different optimization approaches, and gap analysis helps you prioritize where to focus first.
Quick strategies by source type:
* **Editorial:** Focus on digital PR and journalist outreach.
* **Corporate:** Explore partnerships and directory listings.
* **UGC:** Engage authentically in communities or work with influencers.
* **Reference:** Update incomplete information through proper channels.
* **Your own website:** Optimize content structure and ensure AI readability.
For URLs, you’ll see what types of web pages get cited (Articles, Listicles, How-to Guides, Comparisons, etc.). Same as source types, you can use this information to adjust your content strategy and create formats that perform well in your industry.
# Understanding your performance
Source: https://docs.peec.ai/understanding-your-performance
Your main analytics hub for tracking AI search performance across prompts and competitors.
[Watch "Understanding your performance" on YouTube](https://youtu.be/xuXNzv51Mjo)
Your **Overview** dashboard shows three key areas of your AI search performance, plus **Recent Chats** and powerful filters to focus your analysis:
1. **Visibility graph:** See where you stand against competitors across all your prompts with daily fluctuations.
2. **Brands:** Your average visibility percentage, sentiment and position compared to top competitors.
3. **Top Sources:** Which websites and domains AI platforms reference most when answering your prompts, including a chart with source types used (Corporate, Editorial, etc.)
4. **Recent Chats:** Your latest AI responses across all prompts. By default, you’ll see all recent responses, but you can toggle on to show only your brand mentions.
You can click on individual competitors, domains, and chats throughout the dashboard to dive deeper into specific performance details.
## Dashboard filters
Use the filter options at the top of your dashboard to focus your analysis:
* **Competitor**: Filter by competitor to understand their visibility and which sources are being used for them when AIs generate an answer.
* **Date range:** View data for different time periods (default is last 7 days). You can select predefined ranges or create custom date spans. Change indicators compare performance to the previous time span of the same length.
* **Tags:** Filter by specific prompt tags using AND/OR logic. Select multiple tags to focus on prompts that meet your conditions.
* **Models:** Focus on specific AI platforms (ChatGPT, Claude, Perplexity). 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.
Tag filters don't apply to the **Recent Chats** section, you'll always see all recent chats regardless of tag selections.
The **country** filter becomes available once you have added more than one prompt in a different market.
The **tag** and **topic** filters become available once you have assigned any of these to your prompts.
## 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 spot trends in who's gaining or losing ground in AI responses.
**What you see:** Each line represents a different brand's visibility percentage over your selected time period. Hover over the graph to see exact percentages and identify which competitor each line 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 platforms mention your brand when answering relevant prompts. 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:** Average ranking when your brand appears in AI responses (lower numbers are better). Shows where you rank compared to competitors when mentioned. Position 1 means you’re mentioned first, position 5 means fifth, and so on.
Click **Show All** to view the complete ranking with all competitors you've set up.
Read more about identifying and adding competitor brands [here](https://docs.peec.ai/identifying-your-competitors).
### Top Sources
The **Top Sources** section shows you which websites AI platforms trust most when answering your prompts, split by **Source Type** and **Domain**:
* **Sources Type chart:** Shows the number of citations by domain category (Editorial, Corporate, UGC, etc.). This helps you understand what types of sources dominate in your industry.
* **Top Domains table:** Lists the 6 most-used domains with their metrics:
* **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.
* **Citation Rate:** Average number of times the domain was explicitly cited when used.
* **Type:** Domain category classification.
Click **Show All** to access the complete **Sources** section for more detailed analysis.
To learn more in-depth about **Sources**, head over to this section.
### Recent Chats
These are the actual chats we create by running your prompts daily against AI platforms. By default, you'll see all recent chats with an easy filter option to show only chats that mention your brand.
If your visibility is zero for certain prompts, you can still see that prompts are running and understand what AI platforms are saying about your topic area.
Each chat shows the prompt that was run to generate this chat, your brand's position if mentioned, logos of tracked brands that were mentioned, sentiment score, and when this chat was run.
Click on any chat to see it in detail.
## Prompts
Navigate to **Prompts** in your sidebar to see all your prompts. 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.
Prompt status tabs include:
* **Active:** Currently running prompts with full metrics.
* **Suggested:** Generated prompt suggestions with **Volume** data, suggestion date, and **Reject**/**Track** buttons.
* **Inactive:** Previously paused prompts you can reactivate.
Active prompts show these metrics:
* **Visibility:** Percentage of chats mentioning your or competitor's brand in the selected time period.
* **Sentiment:** Brand's sentiment score when mentioned in the selected time period.
* **Position:** Brand's average position when mentioned in the selected time period.
* **Mentions:** Brands mentioned in answers to this prompt or topic.
* **Volume:** Estimated prompt search volume relative to your industry (hover over the colored bar for descriptions like "very low" to "very high"). *This feature is currently in beta.*
* **Tags:** Tags you've added to organize prompts.
* **Location:** Geographic location where the prompt runs.
* **Added:** When you created the prompt.
### Individual prompt dashboards
Click any active prompt to see focused analytics for that specific prompt. You'll see the same dashboard layout as your main **Overview,** but filtered to just that prompt.
Key differences:
* **No tag filters:** Since you're already viewing a specific prompt.
* **Competitor filter available:** Add specific competitors to the Visibility graph and **Brands** ranking table. Your brand appears by default, but you can select additional competitors to compare against (one at a time. If they're not in the top 7, they'll appear at the bottom of the table with their actual ranking (e.g., #36).
* **Fanout Queries** (only available for ChatGPT, Perplexity and Copilot): Shows the latest tracked query fanouts, allowing you to see what similar queries the model performed while creating an answer for the specific prompt. You can now get a granular view of the fanout queries by navigating to the **Query Fanouts** tab in your sidebar.
* **Common terms**: You can also see what the most commonly used terms are across the different query fanouts.
* **Recent chats in table format:** Shows recent responses in a structured table rather than chat cards.
This gives you granular insight into how individual prompts perform and which competitors appear most frequently for specific questions.
### Query fanouts
To see a detailed breakdown of fanout queries, open the **Query Fanouts** tab in the sidebar.
![Fanout Queries Tab]()
### What the page shows
AI models often run background searches before generating a response. The two metrics 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 the 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.
* **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 visible as a brand. And you can be mentioned as a brand without your website being used.
Peec tracks both, so you can spot 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 name with a topic, but not trust your content as a reference.
# Brand insights
Source: https://docs.peec.ai/untitled-page
**Brand Insights** is a deep-dive hub for analyzing how a single brand performs across topics, models, countries, and competitors. Pick a brand and see where it dominates and how it compares with others across every dimension you track.
## **Overview**
The Brand Insights page has six main KPIs. Each of them will give you a different view of your brand and competitors.
![Screenshot 2026 07 29 At 14 52 33]()
### **Main KPIs**
A summary of the selected brand’s performance over your chosen time period:
* **Visibility:** Percentage of AI responses where this brand appears.
* **Share of Voice:** This brand’s share of all brand mentions across your tracked prompts.
* **Sentiment:** How positively AI platforms describe this brand (0–100 scale).
* **Position:** Average ranking when this brand appears in AI responses (lower is better).
* **Strongest / Weakest model:** The AI model where your brand performs best, based on combined visibility, sentiment, and position.
Change indicators show how each metric moved compared with the previous period of the same length.
You can change the brand you are looking at by using the brand filter in the top menu.
### Brand insights graph
The graph shows the brand's performance over time. Toggle between Visibility, Sentiment, Position, 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.
![Brand Insights]()
Switch between Daily, Weekly, or Monthly timeframes using the selectors in the upper-right corner of the graph.
### Performance matrix
A configurable matrix that crosses any two dimensions against each other. You control both axes, choosing from:
* **Models** (ChatGPT, Claude, Perplexity, etc.)
* **Brands** (competitors)
* **Topics**
* **Tags**
* **Countries**
Pick which metric to view (Visibility, Sentiment, Position, 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 Perplexity?
* Where is a competitor outperforming my brand, and in which specific markets?
![Performance Matrix 1]()
Use the actions menu on any section to save or copy the view as an image, or export it as CSV.
### 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. Use the metric control to choose whether ranks are ordered by Visibility, Share of Voice, Sentiment, or Position.
![Brand Insights Ranking 2]()
# Upload and manage your products
Source: https://docs.peec.ai/uploading-products
Bring your product catalog into Peec to track AI Shopping visibility at the product level.
AI Shopping shows how individual products from your catalog appear across AI models, which products are being recommended, which competitors appear alongside them, and how performance changes over time. This guide walks you through everything you need to get your catalog connected so product-level tracking can begin.
You'll learn what data Peec AI needs, the three ways to import your catalog, and the exact CSV format required for uploads. Once your products are live on the **Products** page, AI Shopping 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. |
You can [**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.
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 runs complete.
### 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.
## Managing your catalog
Switch between catalog and chat-discovered products, add them to your catalog over time, and remove products you don't want to track.
Your catalog isn't a one-time upload. This page covers how to work with it after the first import, and how to use AI Shopping without uploading anything at all.
### 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 drafts a category tree from your data and shows it to you before anything goes live. Review it, adjust where needed, and confirm. Your products then land on the Products page, organized by those categories.
Categories drive the filters and breakdowns across AI Shopping, so it's worth getting this step right.
If you upload a CSV while you already have products, the new rows are added to your existing catalog, and nothing gets replaced. To add a single product, a CSV with a single row is sufficient.
### 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**.
After an upload, Peec AI doesn't start from zero. Your products are matched against chats from the last 30 days, so visibility, position, and competitor signals are populated based on history rather than starting from scratch.
# URLs
Source: https://docs.peec.ai/urls
## URLs overview
![Image]()
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 Retrieval by URLs graph:** 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.
![URL Domain Classification]()
## URL metrics
On the URL page, you will see key metrics such as **Retrievals** and **Citation Rate**.
![Untitled Design (11)]()
### 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.
![URL Detail Page]()
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**.
![Bookmarking UR Ls]()
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 agent analytics use cases to improve your visibility and performance in AI search.
## Standalone log file-based benefits & use cases
1. **Know which AI bots are actually visiting your site:** Server logs tell you which bots are visiting (GPTBot, ClaudeBot, PerplexityBot, etc.), how frequently, and which parts of your site. This is pure observability - no prompt tracking needed to answer "is my site being indexed by AI crawlers at all?"
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
[Watch "Welcome to Peec AI" on YouTube](https://youtu.be/FfF7rCUayEc)
## Quickstart Guide
[Watch "Peec AI Product Walkthrough" on YouTube](https://youtu.be/CT4aKlOouFQ)
## Setting up your prompts
[Watch "Setting up your prompts" on YouTube](https://youtu.be/wcbmAs4Q-oE)
## Organizing your setup
[Watch "Organizing your setup" on YouTube](https://youtu.be/_9Z43OpAumM)
## Identifying your competitors
[Watch "Identifying your competitors" on YouTube](https://youtu.be/sS9tgmX1naw)
## Understanding chats
[Watch "Understanding chats" on YouTube](https://youtu.be/EnxfmarTlrg)
## Understanding your performance
[Watch "Understanding your performance" on YouTube](https://youtu.be/xuXNzv51Mjo)
## Understanding sources
[Watch "Understanding your sources" on YouTube](https://youtu.be/OOh0SVkKN4w)
## Managing Your Project
[Watch "Managing your project for brands" on YouTube](https://youtu.be/2bJ9OZy2-cE)
## Crawl Insights
[Watch "Agent Analytics - Peec AI" on YouTube](https://youtu.be/xr099LCVWhg)
[Watch "Agent Analytics - Connecting to Cloudflare" on YouTube](https://youtu.be/5y3ZZfTEfMQ)