list_projects
List active projects the authenticated user has access to. By default, only projects with an active status (CUSTOMER, PITCH, TRIAL, ONBOARDING, API_PARTNER) are returned. Set include_inactive to true to include ended/paused projects. Returns columnar JSON: {columns, rows, rowCount}. Columns: id, name, status. The id is used as project_id in other tools. Call this first to discover available projects.
list_topics
List topics in a project. Topics are folder-like groupings — each prompt belongs to exactly one topic. Use this tool to resolve topic names to IDs before filtering (topic_id filter/dimension, list_prompts), and to label topic IDs from report output with their human-readable names before presenting results. Returns columnar JSON: {columns, rows, rowCount}. Columns: id, name.
list_tags
List tags in a project. Tags are cross-cutting labels that can be assigned to any prompt. Use this tool to resolve tag names to IDs before filtering (tag_id filter/dimension, list_prompts), and to label tag IDs from report output with their human-readable names before presenting results. Returns columnar JSON: {columns, rows, rowCount}. Columns: id, name.
list_brands
List brands tracked in a project — includes the user's own brand and competitors. Use this tool to resolve brand names to IDs before filtering reports (brand_id filter), and to label brand IDs from report output with their human-readable names before presenting results. Returns columnar JSON: {columns, rows, rowCount}. Columns: id, name, domains, is_own. is_own indicates which brand belongs to the user.
list_models
List AI engines (models) tracked by Peec. Use this tool to resolve model names (e.g., "ChatGPT", "Perplexity", "Gemini") to IDs before filtering reports (model_id filter/dimension), and to label model IDs from report output with their human-readable names before presenting results. Match user-supplied names against the name column; the id column is the canonical string to pass back as model_id. is_active indicates whether the model is enabled for this project — inactive models will return empty data in reports. Returns columnar JSON: {columns, rows, rowCount}. Columns: id, name, is_active.
list_prompts
List prompts (conversational questions tracked daily across AI engines) in a project. Supports filtering by topic_id and tag_id. Use this tool to resolve prompt text to IDs before filtering reports (prompt_id filter/dimension), and to label prompt IDs from report output with their actual text before presenting results. Returns columnar JSON: {columns, rows, rowCount}. Columns: id, text, tag_ids (array of tag ID strings), topic_id (string or null).
list_chats
List chats (individual AI responses) for a project over a date range. Each chat is produced by running one prompt against one AI engine on a given date.
Filters:
- brand_id: only chats that mentioned the given brand
- prompt_id: only chats produced by the given prompt
- model_id: only chats from the given AI engine (chatgpt-scraper, gpt-4o, gpt-4o-search, gpt-3.5-turbo, llama-sonar, perplexity-scraper, sonar, gemini-2.5-flash, gemini-scraper, google-ai-overview-scraper, google-ai-mode-scraper, llama-3.3-70b-instruct, deepseek-r1, claude-3.5-haiku, claude-haiku-4.5, claude-sonnet-4, grok-scraper, microsoft-copilot-scraper, grok-4)
Use the returned chat IDs with get_chat to retrieve full message content, sources, and brand mentions.
Returns columnar JSON: {columns, rows, rowCount}. Columns: id, prompt_id, model_id, date.
get_chat
Get the full content of a single chat (one AI engine's response to one prompt on one date). Returns:
- 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 }
Use list_chats to discover chat IDs for a project.
get_brand_report
Get a report on brand visibility, sentiment, and position across AI search engines.
Results are aggregated for the entire date range by default. Use the "date" dimension for daily breakdowns.
Returns columnar JSON: {columns, rows, rowCount, total}. Each row is an array of values matching column order. Columns:
- brand_id — the brand ID
- brand_name — the brand name
- visibility: 0–1 ratio — fraction of AI responses that mention this brand. 0.45 means 45% of conversations.
- mention_count: number of times the brand was mentioned
- share_of_voice: 0–1 ratio — brand's fraction of total mentions across all tracked brands
- sentiment: 0–100 scale — how positively AI platforms describe the brand (most brands score 65–85)
- position: average ranking when the brand appears (lower is better, 1 = mentioned first)
- Raw aggregation fields (for custom calculations): visibility_count, visibility_total, sentiment_sum, sentiment_count, position_sum, position_count
When dimensions are selected, rows also include the relevant dimension columns: prompt_id, model_id, tag_id, topic_id, chat_id, date, country_code.
Dimensions explained:
- prompt_id: individual search queries/prompts
- model_id: AI search engine (e.g. chatgpt-scraper, gpt-4o, gpt-4o-search, gpt-3.5-turbo, llama-sonar, perplexity-scraper, sonar, gemini-2.5-flash, gemini-scraper, google-ai-overview-scraper, google-ai-mode-scraper, llama-3.3-70b-instruct, deepseek-r1, claude-3.5-haiku, claude-haiku-4.5, claude-sonnet-4, grok-scraper, microsoft-copilot-scraper, grok-4)
- tag_id: custom user-defined tags
- topic_id: topic groupings
- date: (YYYY-MM-DD format)
- country_code: country (ISO 3166-1 alpha-2, e.g. "US", "DE")
- chat_id: individual AI chat/conversation ID
Filters use {field, operator, values} where operator is "in" or "not_in". Filterable fields: model_id, tag_id, topic_id, prompt_id, brand_id, country_code, chat_id.
get_domain_report
Get a report on source domain visibility and citations across AI search engines.
Results are aggregated for the entire date range by default. Use the "date" dimension for daily breakdowns.
Returns columnar JSON: {columns, rows, rowCount}. Each row is an array of values matching column order. Columns:
- domain: the source domain (e.g. "example.com")
- classification: domain type — CORPORATE (official company sites), EDITORIAL (news, blogs, magazines), INSTITUTIONAL (government, education, nonprofit), UGC (social media, forums, communities), REFERENCE (encyclopedias, documentation), COMPETITOR (direct competitors), OWN (the user's own domains), OTHER, or null
- retrieved_percentage: 0–1 ratio — fraction of chats that included at least one URL from this domain. 0.30 means 30% of chats.
- retrieval_rate: average number of URLs from this domain pulled per chat. Can exceed 1.0 — values above 1.0 mean multiple pages from the same domain are retrieved per conversation.
- citation_rate: average number of inline citations when this domain is retrieved. Can exceed 1.0 — higher values indicate stronger content authority.
When dimensions are selected, rows also include the relevant dimension columns: prompt_id, model_id, tag_id, topic_id, chat_id, date, country_code.
Dimensions explained:
- prompt_id: individual search queries/prompts
- model_id: AI search engine (e.g. chatgpt-scraper, gpt-4o, gpt-4o-search, gpt-3.5-turbo, llama-sonar, perplexity-scraper, sonar, gemini-2.5-flash, gemini-scraper, google-ai-overview-scraper, google-ai-mode-scraper, llama-3.3-70b-instruct, deepseek-r1, claude-3.5-haiku, claude-haiku-4.5, claude-sonnet-4, grok-scraper, microsoft-copilot-scraper, grok-4)
- tag_id: custom user-defined tags
- topic_id: topic groupings
- date: (YYYY-MM-DD format)
- country_code: country (ISO 3166-1 alpha-2, e.g. "US", "DE")
- chat_id: individual AI chat/conversation ID
Filters use {field, operator, values} where operator is "in" or "not_in". Filterable fields: model_id, tag_id, topic_id, prompt_id, domain, url, country_code, chat_id.
get_url_report
Get a report on source URL visibility and citations across AI search engines.
Results are aggregated for the entire date range by default. Use the "date" dimension for daily breakdowns.
Returns columnar JSON: {columns, rows, rowCount}. Each row is an array of values matching column order. Columns:
- url: the full source URL (e.g. "https://example.com/page")
- classification: page type — HOMEPAGE, CATEGORY_PAGE, PRODUCT_PAGE, LISTICLE (list-structured articles), COMPARISON (product/service comparisons), PROFILE (directory entries like G2 or Yelp), ALTERNATIVE (alternatives-to articles), DISCUSSION (forums, comment threads), HOW_TO_GUIDE, ARTICLE (general editorial content), OTHER, or null
- title: page title or null
- citation_count: total number of explicit citations across all chats
- retrievals: total number of times this URL was used as a source, regardless of whether it was cited
- citation_rate: average number of inline citations per chat when this URL is retrieved. Can exceed 1.0 — higher values indicate more authoritative content.
When dimensions are selected, rows also include the relevant dimension columns: prompt_id, model_id, tag_id, topic_id, chat_id, date, country_code.
Dimensions explained:
- prompt_id: individual search queries/prompts
- model_id: AI search engine (e.g. chatgpt-scraper, gpt-4o, gpt-4o-search, gpt-3.5-turbo, llama-sonar, perplexity-scraper, sonar, gemini-2.5-flash, gemini-scraper, google-ai-overview-scraper, google-ai-mode-scraper, llama-3.3-70b-instruct, deepseek-r1, claude-3.5-haiku, claude-haiku-4.5, claude-sonnet-4, grok-scraper, microsoft-copilot-scraper, grok-4)
- tag_id: custom user-defined tags
- topic_id: topic groupings
- date: (YYYY-MM-DD format)
- country_code: country (ISO 3166-1 alpha-2, e.g. "US", "DE")
- chat_id: individual AI chat/conversation ID
Filters use {field, operator, values} where operator is "in" or "not_in". Filterable fields: model_id, tag_id, topic_id, prompt_id, domain, url, country_code, chat_id.