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:

{
  "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

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

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) — 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.

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 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. This is not the same as 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. 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 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 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`.
`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` 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 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.

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.

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)
`order_by`	object[]	No	Sort by one or more fields (see 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)
`order_by`	object[]	No	Sort by one or more fields (see 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 when retrieved. Can exceed 1.0
`retrieval_count`	number	Total distinct URL retrievals from this domain across all chats (raw numerator of `retrieval_rate`)
`citation_count`	number	Total citations from this domain (raw count)
`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)
`order_by`	object[]	No	Sort by one or more fields (see 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. 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.

search_docs

Search the Peec product documentation at 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. 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 the full markdown content of a single documentation page. Pass the path returned by 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`: `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`: `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 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`: `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`: `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) 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). 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). 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 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.

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

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 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:

{
  "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` 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`.
`url_classification`	URL report	Built-in classification display name (`Listicle`, `Comparison`, …) or the name of a custom URL classification. See `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.

{
  "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.

{
  "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.

[
  { "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.

​Response format

​list_projects

​list_brands

​list_topics

​list_tags

​list_tag_groups

​list_models

​list_model_channels

​list_prompts

​list_chats

​get_chat

​list_search_queries

​list_shopping_queries

​list_products

​get_product

​get_shopping_attributes

​get_shopping_summary

​get_shopping_trend

​list_shopping_demand

​list_shopping_performance

​list_categories

​list_global_brands

​list_bots

​get_agent_visits

​Group-by dimensions

​Response fields

​list_domain_classifications

​list_url_classifications

​get_brand_report

​Parameters

​Response fields

​get_domain_report

​Parameters

​Response fields

​get_url_report

​Parameters

​Response fields

​get_url_content

​Response fields

​get_actions

​Parameters

​Response (scope=overview)

​Response (scope=owned | editorial | reference | ugc)

​get_project_profile

​search_docs

​read_doc

​Write tools

​create_brand

​update_brand

​delete_brand

​create_brands

​delete_brands

​update_brands

​create_prompt

​update_prompt

​delete_prompt

​create_prompts

​delete_prompts

​update_prompts

​archive_prompt

​unarchive_prompt

​create_tag

​update_tag

​delete_tag

​create_tags

​delete_tags

​update_tags

​update_tag_group

​delete_tag_group

​create_topic

​update_topic

​delete_topic

​create_topics

​delete_topics

​update_topics

​create_products

​update_products

​delete_products

​create_categories

​update_categories

Response format

list_projects

list_brands

list_topics

list_tags

list_tag_groups

list_models

list_model_channels

list_prompts

list_chats

get_chat

list_search_queries

list_shopping_queries

list_products

get_product

get_shopping_attributes

get_shopping_summary

get_shopping_trend

list_shopping_demand

list_shopping_performance

list_categories

list_global_brands

list_bots

get_agent_visits

Group-by dimensions

Response fields

list_domain_classifications

list_url_classifications

get_brand_report

Parameters

Response fields

get_domain_report

Parameters

Response fields

get_url_report

Parameters

Response fields

get_url_content

Response fields

get_actions

Parameters

Response (`scope=overview`)

Response (`scope=owned` | `editorial` | `reference` | `ugc`)

get_project_profile

search_docs

read_doc

Write tools

create_brand

update_brand

delete_brand

create_brands

delete_brands

update_brands

create_prompt

update_prompt

delete_prompt

create_prompts

delete_prompts

update_prompts

archive_prompt

unarchive_prompt

create_tag

update_tag

delete_tag

create_tags

delete_tags

update_tags

update_tag_group

delete_tag_group

create_topic

update_topic

delete_topic

create_topics

delete_topics

update_topics

create_products

update_products

delete_products

create_categories

update_categories