The Peec AI MCP Server exposes two sets of tools:

Read tools (19) return data: projects, brands, model channels, prompts, chats, reports, actions, scraped source content, custom classifications, and the brand profile.
Write tools (29) create, update, or delete brands, prompts, tags, topics, 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 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_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, and get_project_profile 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
`limit`	number	No	Max results (default: 100)
`offset`	number	No	Results to skip (default: 0)

Columns: id, name

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

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
`prompt`	`{id}`
`model`	`{id}`

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

Write tools

Write tools let the assistant edit your project configuration: brands, prompts, tags, topics, 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, delete_brands, create_prompts, delete_prompts, create_tags, delete_tags, create_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. 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" }]

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 }]

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)

Returns: { id }. The created tag ID.

update_tag

Update a tag’s name or color.

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

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`

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" }]

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" }]

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.

Overview

Reference

Documentation Index

​Response format

​list_projects

​list_brands

​list_topics

​list_tags

​list_models

​list_model_channels

​list_prompts

​list_chats

​get_chat

​list_search_queries

​list_shopping_queries

​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

​Write tools

​create_brand

​update_brand

​delete_brand

​create_brands

​delete_brands

​create_prompt

​update_prompt

​delete_prompt

​create_prompts

​delete_prompts

​create_tag

​update_tag

​delete_tag

​create_tags

​delete_tags

​create_topic

​update_topic

​delete_topic

​create_topics

​delete_topics

​create_domain_classification

​delete_domain_classification

​assign_domain_classification

​unassign_domain_classification

​create_url_classification

​delete_url_classification

​assign_url_classification

​unassign_url_classification

​set_project_profile

​Report filters and dimensions

​Filtering

​Standard filter fields

​Numeric filters

​Operators

​Sorting

​Dimensions

Response format

list_projects

list_brands

list_topics

list_tags

list_models

list_model_channels

list_prompts

list_chats

get_chat

list_search_queries

list_shopping_queries

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

Write tools

create_brand

update_brand

delete_brand

create_brands

delete_brands

create_prompt

update_prompt

delete_prompt

create_prompts

delete_prompts

create_tag

update_tag

delete_tag

create_tags

delete_tags

create_topic

update_topic

delete_topic

create_topics

delete_topics

create_domain_classification

delete_domain_classification

assign_domain_classification

unassign_domain_classification

create_url_classification

delete_url_classification

assign_url_classification

unassign_url_classification

set_project_profile

Report filters and dimensions

Filtering

Standard filter fields

Numeric filters

Operators

Sorting

Dimensions