> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics and reporting

> Understand the analytics and reporting tools available through Profound MCP

Profound MCP gives AI assistants read-only access to Profound's Answer Engine Optimization (AEO), brand visibility, citation, sentiment, shopping, prompt volume, and Agent Analytics data. Use this page to understand what the hosted MCP server can do before connecting it to an MCP client. When you're ready to connect, refer to the [Connection guides](/mcp/common-mcp-clients).

## How the tools work together

Most conversations start with the [discovery tools](/mcp/capabilities/discovery-tools), then move into reports. Here's what that typically looks like:

<Steps>
  <Step title="Confirm access">
    Ask what data you can see. The assistant confirms the signed-in user, available organizations, regions, and entitlements with [`whoami`](/mcp/capabilities/discovery-tools#whoami).
  </Step>

  <Step title="Find the right scope">
    Ask about the brand or site you care about. The assistant resolves it with [`list_organizations`](/mcp/capabilities/discovery-tools#list-organizations), then [`list_categories`](/mcp/capabilities/discovery-tools#list-categories) for visibility reports or [`list_domains`](/mcp/capabilities/discovery-tools#list-domains) for traffic reports.
  </Step>

  <Step title="Add optional filters">
    Ask to narrow the question to a market, AI engine, prompt set, topic, or tag. The assistant resolves those filters with [`list_regions`](/mcp/capabilities/discovery-tools#list-regions), [`list_models`](/mcp/capabilities/discovery-tools#list-models), [`list_tags`](/mcp/capabilities/discovery-tools#list-tags), [`list_topics`](/mcp/capabilities/discovery-tools#list-topics), and [`list_prompts`](/mcp/capabilities/prompts-capabilities#list-prompts).
  </Step>

  <Step title="Run a report">
    Ask about what you want reported. The assistant retrieves visibility, sentiment, citations, prompt answers, shopping, prompt volume, referrals, or bot crawl data for the date range you name.
  </Step>
</Steps>

## Behavior and safety

All tools are read-only. They retrieve analytics data, but don't create, update, or delete anything in Profound.

| Behavior | What it means |
| - | - |
| Non-destructive | No tool performs destructive updates |
| Live data | Tools read from the Profound API, so results reflect the caller's current access and data |

All report tools set the following MCP hints:

| Hint | Value | What it means |
| - | - | - |
| `readOnlyHint` | `true` | The tool only reads data |
| `idempotentHint` | `true` | The tool is safe to retry with the same arguments |

Dates are ISO 8601 strings in `YYYY-MM-DD` format. Reports validate `start_date` and `end_date` and return an actionable error if the date window is invalid.

## Visibility reports

These tools are scoped to a `category_id` and a date range. Use them to understand how brands appear in AI answers, both in regular text answers and in [shopping mode](https://help.tryprofound.com/articles/8862399588-about-shopping) results.

### Brand visibility reports

Use these tools to understand how brands appear in AI answers, how those answers feel, how accurate they are, and which sources AI engines cite.

| Tool | Usage |
| - | - |
| `get_visibility_report` | How visible a brand is in AI answers and how that varies by model, topic, region, prompt, or persona |
| `get_sentiment_report` | What sentiment AI answers express about one brand or competitor and which themes and claims drive it |
| `get_citations_report` | Which domains and pages AI engines cite for this category |
| `get_prompt_answers` | What raw AI answers Profound observed behind the metrics |
| `get_factcheck_report` | FactCheck scores for a category over a date range |
| `get_factcheck_claims` | Inaccurate claims identified in a category over a date range |

<AccordionGroup>
  <Accordion title="get_visibility_report" id="get-visibility-report">
    Measures how often and how prominently a brand appears in AI answers for a category over a date range.

    **Example prompts**:

    * "How visible were we in AI answers last month, broken down by model?"
    * "Are we gaining or losing visibility against competitors this quarter?"

    Default metric: `visibility_score`. The other metrics are `share_of_voice` and `average_position`.

    `visibility_score` is a raw decimal. Multiply it by 100 to match the percentage the Profound platform shows, so `0.42` is 42%.

    **Inputs**

    | Input | Required | Default | Description |
    | - | - | - | - |
    | `category_id` | Yes | - | Category to report on |
    | `start_date` | Yes | - | Window start (inclusive) in `YYYY-MM-DD` format |
    | `end_date` | Yes | - | Window end (inclusive) in `YYYY-MM-DD` format |
    | `group_by` | No | `null` | Group results by `date`, `model`, `topic`, `region`, `prompt`, or `persona` |
    | `metrics` | No | `visibility_score` | Metrics to return: `visibility_score`, `share_of_voice`, or `average_position` |
    | `interval` | No | `day` | Size of each time bucket when grouping by `date`: `day`, `week`, or `month` |
    | `scope` | No | `owned` | `owned` for your tracked brands, or `all` to include competitors |
    | `assets` | No | `null` | Narrow to one or more brands, by name |
    | `topic_filter` | No | `null` | Narrow to one or more topics |
    | `tag_filter` | No | `null` | Narrow to one or more tags |
    | `region_filter` | No | `null` | Narrow to one or more regions |
    | `model_filter` | No | `null` | Narrow to one or more AI models, by ID from `list_models` |
    | `persona_filter` | No | `null` | Narrow to one or more personas, by ID |
    | `filter` | No | `null` | Filter expression for conditions the other inputs can't express, such as excluding one region or matching either of two topics. Combined with those inputs using `and` |
    | `limit` | No | `null` | Top-level groups per page, up to 50 |
    | `cursor` | No | `null` | Pagination token from `info.next_cursor` |

    **Notes**:

    * Every row carries an `asset` object of `{name, owned}`. Results are always grouped by brand as well as by `group_by`, so you get one row per brand per bucket.
    * `limit` caps top-level groups rather than rows, so a grouped query returns more rows than the limit you set.
  </Accordion>

  <Accordion title="get_sentiment_report" id="get-sentiment-report">
    Measures the sentiment AI answers express about one brand or competitor in a category over a date range, or the sentiment of the pages those answers cite.

    **Example prompts**:

    * "How do AI answers feel about our pricing?"
    * "Which cited pages are most negative about our brand?"

    Sentiment comes from either the answers themselves or the pages they cite, and `source` selects which.

    **Inputs**

    | Input | Required | Default | Description |
    | - | - | - | - |
    | `category_id` | Yes | - | Category to report on |
    | `asset` | Yes | - | Brand or competitor name to analyze |
    | `start_date` | Yes | - | Window start (inclusive) in `YYYY-MM-DD` format |
    | `end_date` | Yes | - | Window end (inclusive) in `YYYY-MM-DD` format |
    | `source` | No | `response` | `response` for tone in AI answers, `citation` for tone on cited pages |
    | `group_by` | No | `[]` | Group response rows by `date`, `model`, `topic`, `region`, `prompt`, `persona`, `tag`, `theme`, or `claim`. Takes at most two non-date groupings, plus `date` for a time series |
    | `theme` | No | `null` | Narrow to one sentiment theme, such as pricing |
    | `claim` | No | `null` | Narrow to one claim |
    | `model` | No | `null` | Narrow to one or more AI models |
    | `citation_category` | No | `null` | Narrow to one or more citation categories, including custom category names |
    | `page_contains` | No | `null` | Narrow to pages whose URL contains this text. Case doesn't matter |
    | `citation_sort_by` | No | `citation_share` | Sort citation rows by `citation_share` or `positive_sentiment` |
    | `citation_sort_direction` | No | `desc` | Sort direction, `asc` or `desc` |
    | `limit` | No | `10` | Rows per page, up to 50 |
    | `cursor` | No | `null` | Pagination token from `info.next_cursor` |

    **Notes**:

    * `citation_category`, `page_contains`, `citation_sort_by`, and `citation_sort_direction` are available only when `source` is `citation`, and return an error otherwise.
    * Filters narrow results, and never group them. When `source` is `citation`, the `model` changes which pages qualify and their citation share, but the sentiment is still for the page, not for the model.
  </Accordion>

  <Accordion title="get_citations_report" id="get-citations-report">
    Shows which sources AI engines cite for a category, and how often, over a date range.

    **Example prompts**:

    * "Which sites do AI engines cite most in our category?"
    * "How often do AI answers cite our own domain?"

    Default metrics: `count` and `citation_share`. `count` is raw citation frequency, and `citation_share` is averaged per AI model so it stays comparable across models.

    With no `group_by`, each row is one cited domain, ranked most cited first. Use that default to find which sites AI engines cite most.

    <Note>
      `group_by: ["page"]` returns one row per cited page and can't be combined with `scope: "owned"` or `domain_filter`, which both narrow to a domain.
    </Note>

    **Inputs**

    | Input | Required | Default | Description |
    | - | - | - | - |
    | `category_id` | Yes | - | Category to report on |
    | `start_date` | Yes | - | Window start (inclusive) in `YYYY-MM-DD` format |
    | `end_date` | Yes | - | Window end (inclusive) in `YYYY-MM-DD` format |
    | `group_by` | No | `null` | Group results by `page`, `date`, `model`, `topic`, `region`, `persona`, or `prompt` |
    | `metrics` | No | `count`, `citation_share` | Metrics to return: `count`, `citation_share`, `rank`, or `first_cited_at` |
    | `interval` | No | `day` | Size of each time bucket when grouping by `date`: `day`, `week`, or `month` |
    | `scope` | No | `all` | `all` to cover every cited domain, or `owned` to narrow to your own domains |
    | `topic_filter` | No | `null` | Narrow to one or more topics |
    | `region_filter` | No | `null` | Narrow to one or more regions |
    | `model_filter` | No | `null` | Narrow to one or more AI models, by ID from `list_models` |
    | `persona_filter` | No | `null` | Narrow to one or more personas, by ID |
    | `domain_filter` | No | `null` | Narrow to one or more domains, including their subdomains |
    | `page_filter` | No | `null` | Narrow to one or more page URLs |
    | `citation_category_filter` | No | `null` | Narrow to one or more citation categories, such as `owned` or `social` |
    | `analysis_type_filter` | No | `null` | Narrow to one analysis type: `visibility`, `sentiment`, `factcheck`, or `all` |
    | `filter` | No | `null` | Filter expression for conditions the other inputs can't express, such as excluding one region or matching either of two topics. Combined with other filter inputs using `and` |
    | `limit` | No | `null` | Top-level groups per page, up to 50 |
    | `cursor` | No | `null` | Pagination token from `info.next_cursor` |

    **Notes**:

    * Every row carries a `rank`, where `1` is the most cited. `first_cited_at` is returned on page rows only.
    * `limit` caps top-level groups rather than rows, so a grouped query returns more rows than the limit you set.
  </Accordion>

  <Accordion title="get_prompt_answers">
    Retrieves the answers AI engines gave for a category's prompts over a date range: the raw text behind the visibility metrics.

    **Example prompts**:

    * "What did AI engines answer for our savings prompts last week?"
    * "Pull the answers behind last month's visibility drop."

    **Inputs**

    | Input | Required | Default | Description |
    | - | - | - | - |
    | `category_id` | Yes | - | Category to retrieve prompt answers for |
    | `start_date` | Yes | - | Window start (inclusive) in `YYYY-MM-DD` format |
    | `end_date` | Yes | - | Window end (inclusive) in `YYYY-MM-DD` format |
    | `prompt_id` | No | `null` | Narrow the results to a single prompt |
    | `country` | No | `null` | Narrow to one or more countries, by name or ID. Can't be combined with `region` |
    | `region` | No | `null` | Narrow to one or more regions, by name or ID. Can't be combined with `country` |
    | `topic_ids` | No | `null` | Narrow to one or more topics, by ID from `list_topics` |
    | `model_ids` | No | `null` | Narrow to one or more answering AI models, by ID from `list_models` |
    | `limit` | No | `100` | Rows per page |
    | `offset` | No | `0` | Row offset for pagination |

    **Notes**:

    * Several IDs in one list match any of those IDs. When both inputs are set, an answer has to match both.
    * Filters apply before pagination, so a filtered call pages through matching answers only.
  </Accordion>

  <Accordion title="get_factcheck_report" id="get-factcheck-report">
    Reports how accurately AI answers describe a category over a date range: the FactCheck score, its trend, and the accurate and inaccurate counts behind it.

    **Example prompts**:

    * "What's our FactCheck score for last month?"
    * "Is accuracy improving, and which models are least accurate?"

    Rows always return `accuracy`, `accurate`, and `inaccurate`. With no `group_by`, the report returns the headline score for the category.

    **Inputs**

    | Input | Required | Default | Description |
    | - | - | - | - |
    | `category_id` | Yes | - | Category to report on |
    | `start_date` | Yes | - | Window start (inclusive) in `YYYY-MM-DD` format |
    | `end_date` | Yes | - | Window end (inclusive) in `YYYY-MM-DD` format |
    | `group_by` | No | `[]` | Group results by `date`, `model`, `region`, `persona`, `prompt`, `topic`, `tag`, `citation`, or `theme`. Takes up to two values, and `citation` can't be combined with another value |
    | `model` | No | `null` | Narrow to one or more AI models, by exact name |
    | `topic` | No | `null` | Narrow to one or more topics, by exact name from `list_topics` |
    | `topic_negate` | No | `false` | When `true`, exclude the topics in `topic` instead of narrowing to them |
    | `region` | No | `null` | Narrow to one or more regions, by exact name |
    | `persona` | No | `null` | Narrow to one or more personas, by exact name |
    | `prompt` | No | `null` | Narrow to one or more prompts, by exact name |
    | `tag` | No | `null` | Narrow to one or more tags, by exact name |
    | `limit` | No | `100` | Rows per page, up to 100 |
    | `cursor` | No | `null` | Pagination token from `info.next_cursor` |

    **Notes**:

    * FactCheck is scoped to a category, so there's no brand or competitor input.
    * Filters match names exactly.
    * `topic_negate` applies to `topic` only, and leaves the other filters narrowing as usual.
  </Accordion>

  <Accordion title="get_factcheck_claims" id="get-factcheck-claims">
    Lists the inaccurate claims AI answers made about a category over a date range.

    **Example prompts**:

    * "Which inaccurate claims came up in our category last month?"
    * "What's the evidence behind the most common inaccurate claim, and which pages are cited for it?"

    **Inputs**

    | Input | Required | Default | Description |
    | - | - | - | - |
    | `category_id` | Yes | - | Category to report on |
    | `start_date` | Yes | - | Window start (inclusive) in `YYYY-MM-DD` format |
    | `end_date` | Yes | - | Window end (inclusive) in `YYYY-MM-DD` format |
    | `group_by` | No | `[]` | Group results by one of `model`, `region`, `persona`, `prompt`, `topic`, `tag`, or `theme` |
    | `include` | No | `[]` | Extra detail per claim: `theme`, `reasoning`, `models`, `evidence`, or `citation_sources` |
    | `model` | No | `null` | Narrow to one or more AI models, by exact name |
    | `topic` | No | `null` | Narrow to one or more topics, by exact name from `list_topics` |
    | `topic_negate` | No | `false` | When `true`, exclude the topics in `topic` instead of narrowing to them |
    | `region` | No | `null` | Narrow to one or more regions, by exact name |
    | `persona` | No | `null` | Narrow to one or more personas, by exact name |
    | `prompt` | No | `null` | Narrow to one or more prompts, by exact name |
    | `tag` | No | `null` | Narrow to one or more tags, by exact name |
    | `limit` | No | `25` | Rows per page, up to 100, or up to 5 when `include` contains `citation_sources` |
    | `cursor` | No | `null` | Pagination token from `info.next_cursor` |

    **Notes**:

    * `group_by` takes one value, and `group_by: ["tag"]` can't be combined with a `tag` filter. Grouping by date, citation, or claim isn't supported.
    * `citation_sources` adds the pages cited for each claim, so it can't be combined with `group_by`, and `limit` has to be 5 or less. A higher limit returns an error instead of being reduced automatically.
    * The `include` values add why each claim is inaccurate, which models repeated it, and which pages are cited for it. Those values can be combined, so one ungrouped call can return a claim's theme, reasoning, models, evidence, and citation sources together.
    * For the score, its trend, or accurate and inaccurate counts, use [`get_factcheck_report`](#get-factcheck-report) instead.
  </Accordion>
</AccordionGroup>

### Legacy visibility and citations reports

`get_visibility_report` and `get_citations_report` each have an earlier version that returns the legacy response shape: rows as positional values, grouped with `dimensions` rather than `group_by`, and without the `scope` and `assets` brand scoping. Both remain available for integrations built against the earlier shape.

<Note>
  These tools take a half-open date window: `start_date` is inclusive and `end_date` is exclusive. To cover all of April 2026, pass `start_date: 2026-04-01` and `end_date: 2026-05-01`. The current tools treat both ends as inclusive, so the same dates cover a different window.
</Note>

| Tool | Usage |
| - | - |
| `get_visibility_report_v1` | Visibility for a category, in the legacy response shape |
| `get_citations_report_v1` | Citations for a category, in the legacy response shape |

<AccordionGroup>
  <Accordion title="get_visibility_report_v1" id="get-visibility-report-v1">
    Measures how often and how prominently a brand appears in AI answers for a category over a date range, and returns the legacy response shape. For new integrations, use [`get_visibility_report`](#get-visibility-report) instead.

    Default metric: `visibility_score`.

    Other useful metrics include `share_of_voice`, `mentions_count`, `executions`, and `average_position`. Useful dimensions include `date`, `region`, `topic`, `model`, `prompt`, `tag`, `persona`, and `asset_name`.

    **Inputs**

    | Input | Required | Default | Description |
    | - | - | - | - |
    | `category_id` | Yes | - | Category to report on |
    | `start_date` | Yes | - | Window start (inclusive) in `YYYY-MM-DD` format |
    | `end_date` | Yes | - | Window end (exclusive) in `YYYY-MM-DD` format |
    | `metrics` | No | `visibility_score` | Metrics to return |
    | `dimensions` | No | `null` | Group-by fields |
    | `filters` | No | `null` | Advanced `{ "field", "operator", "value" }` predicates |
    | `limit` | No | `null` | Top-N row cap. When set, `next_cursor` is always `null` |
    | `topic_filter` | No | `null` | Narrow to one or more topics |
    | `tag_filter` | No | `null` | Narrow to one or more tags |
    | `region_filter` | No | `null` | Narrow to one or more regions |
    | `model_filter` | No | `null` | Narrow to one or more AI models |
    | `persona_filter` | No | `null` | Narrow to one or more personas |
    | `asset_filter` | No | `null` | Narrow to one or more brand or competitor assets |
    | `cursor` | No | `null` | Pagination token from a previous response |
    | `page_size` | No | `500` | First-page size, up to 10,000 |

    **Notes**:

    * `visibility_score` is a raw decimal. Multiply it by 100 to match the percentage the Profound platform displays.
    * Without an asset filter or `asset_name` in `dimensions`, `visibility_score` is summed across every tracked brand in the category, so the total can exceed 1. To scope the report to one brand, pass `asset_filter` or add `asset_name` to `dimensions`.
  </Accordion>

  <Accordion title="get_citations_report_v1" id="get-citations-report-v1">
    Shows which sources AI engines cite for a category, and how often, over a date range, and returns the legacy response shape. For new integrations, use [`get_citations_report`](#get-citations-report) instead.

    Default metrics: `count` and `citation_share`. Dimensions include `hostname`, `path`, `root_domain`, `url`, `model`, `topic`, `prompt`, `tag`, and `persona`.

    <Note>
      `root_domain_filter` must be paired with `dimensions: ["root_domain"]`.
    </Note>

    **Inputs**

    | Input | Required | Default | Description |
    | - | - | - | - |
    | `category_id` | Yes | - | Category to report on |
    | `start_date` | Yes | - | Window start (inclusive) in `YYYY-MM-DD` format |
    | `end_date` | Yes | - | Window end (exclusive) in `YYYY-MM-DD` format |
    | `metrics` | No | `count`, `citation_share` | Metrics to return |
    | `dimensions` | No | `null` | Group-by fields |
    | `filters` | No | `null` | Advanced `{ "field", "operator", "value" }` predicates |
    | `limit` | No | `null` | Top-N row cap. When set, `next_cursor` is always `null` |
    | `topic_filter` | No | `null` | Narrow to one or more topics |
    | `tag_filter` | No | `null` | Narrow to one or more tags |
    | `region_filter` | No | `null` | Narrow to one or more regions |
    | `model_filter` | No | `null` | Narrow to one or more AI models |
    | `persona_filter` | No | `null` | Narrow to one or more personas |
    | `root_domain_filter` | No | `null` | Narrow to one or more root domains. Requires `root_domain` in `dimensions` |
    | `hostname_filter` | No | `null` | Narrow to one or more hostnames |
    | `citation_category_filter` | No | `null` | Narrow to one or more citation categories |
    | `cursor` | No | `null` | Pagination token from a previous response |
    | `page_size` | No | `500` | First-page size, up to 10,000 |
  </Accordion>
</AccordionGroup>

### Shopping visibility reports

<Note>
  Shopping analysis data is currently available only for ChatGPT.
</Note>

Use these tools to understand how brands, products, and retailers appear when AI answers a prompt with shopping mode results.

| Tool | Usage |
| - | - |
| `get_shopping_brands_report` | Brand visibility inside AI shopping results |
| `get_shopping_products_report` | Per-product visibility, position share, and offers |
| `get_shopping_merchants_report` | Which retailers ChatGPT surfaces |
| `get_shopping_trigger_rate_report` | How often prompts return shopping results |

<Tip>
  Start by asking the assistant how often the category's prompts return shopping results (`get_shopping_trigger_rate_report`). If they rarely do, the other shopping reports have little data to show.
</Tip>

<AccordionGroup>
  <Accordion title="get_shopping_brands_report">
    Measures how often each brand appears when ChatGPT returns shopping results. This is the shopping counterpart to `get_visibility_report`.

    **Example prompts**:

    * "Which brands appear most in ChatGPT shopping results for our category?"
    * "How does our shopping visibility compare to competitors, day by day?"

    **Inputs**

    | Input | Required | Default | Description |
    | - | - | - | - |
    | `category_id` | Yes | - | Tracked category, from `list_categories` |
    | `start_date` | Yes | - | Window start (inclusive) in `YYYY-MM-DD` format |
    | `end_date` | Yes | - | Window end (inclusive) in `YYYY-MM-DD` format |
    | `group_by` | No | `null` | Group results by `date`, `topic`, `region`, or `prompt` |
    | `metrics` | No | all | Metrics to return |
    | `interval` | No | `day` | Size of each time bucket when grouping by `date`: `day`, `week`, or `month` |
    | `scope` | No | `null` | `owned` for your tracked brands, or `all` to include competitors. Left unset, the report covers your tracked brands |
    | `assets` | No | `null` | Narrow to one or more brands, by name. An `assets` selection returns one page and ignores `limit` |
    | `topic_filter` | No | `null` | Narrow to one or more topics |
    | `region_filter` | No | `null` | Narrow to one or more regions |
    | `persona_filter` | No | `null` | Narrow to one or more personas |
    | `prompt_filter` | No | `null` | Narrow to one or more prompts |
    | `tag_filter` | No | `null` | Narrow to one or more tags |
    | `filter` | No | `null` | Filter expression for conditions the other inputs can't express, such as excluding one region or matching either of two topics. Combined with those inputs using `and` |
    | `limit` | No | `null` | Top-level groups per page, up to 50 |
    | `cursor` | No | `null` | Pagination token from `info.next_cursor` |

    **Notes**:

    * Every row carries an `asset` object of `{name, owned}`, and asset is always an implicit grouping key: results are one row per asset and group-by bucket.
  </Accordion>

  <Accordion title="get_shopping_products_report">
    Measures individual product visibility inside AI shopping results, one row per product plus any group-by bucket.

    **Example prompts**:

    * "How visible are our products in ChatGPT shopping results?"
    * "Where is our flagship product sold, and at what price?"

    **Inputs**

    | Input | Required | Default | Description |
    | - | - | - | - |
    | `category_id` | Yes | - | Tracked category, from `list_categories` |
    | `start_date` | Yes | - | Window start (inclusive) in `YYYY-MM-DD` format |
    | `end_date` | Yes | - | Window end (inclusive) in `YYYY-MM-DD` format |
    | `group_by` | No | `null` | Group the results by `date`, `topic`, or `prompt`. Can't be combined with `target_product` or `include_merchants` |
    | `metrics` | No | all | Metrics to return |
    | `interval` | No | `day` | Size of each time bucket when grouping by `date`: `day`, `week`, or `month` |
    | `target_product` | No | `null` | Switch to the item view: one product plus its closest competitors. Can't be combined with `group_by` or `include_merchants` |
    | `include_merchants` | No | `false` | `true` adds each product's offers as `merchants`, a list of `{name, price}`, plus `product_url` and `product_image_urls` on the product row. Can't be combined with `group_by` or `target_product` |
    | `topic_filter` | No | `null` | Narrow to one or more topics |
    | `region_filter` | No | `null` | Narrow to one or more regions |
    | `persona_filter` | No | `null` | Narrow to one or more personas |
    | `prompt_filter` | No | `null` | Narrow to one or more prompts |
    | `tag_filter` | No | `null` | Narrow to one or more tags |
    | `brand_filter` | No | `null` | Narrow to one brand's products |
    | `merchant_filter` | No | `null` | Narrow to the products one retailer surfaces |
    | `filter` | No | `null` | Filter expression for conditions the other inputs can't express, such as excluding one region or matching either of two topics |
    | `limit` | No | `null` | Top-level groups per page, up to 50 |
    | `cursor` | No | `null` | Pagination token from `info.next_cursor` |

    **Notes and tips**:

    * The default metrics are `visibility_score`, `average_position`, `visibility_rank`, `position1_percentage`, `position2_percentage`, `position3_percentage`, `position_above3_percentage`, `product_rating`, and `product_num_reviews`.
    * The `position` metrics are how your assistant tells "always shown, always fourth" from "sometimes shown first". Each one is a raw 0–1 fraction of the product's appearances at that slot, and together they sum to about 1, so 0.30 is 30%.
    * `include_merchants` mode accepts no `group_by` or `target_product`, and the position-frequency metrics aren't available in it.
  </Accordion>

  <Accordion title="get_shopping_merchants_report">
    Measures which retailers appear in a category's shopping results.

    **Example prompt**:

    * "Which retailers does ChatGPT surface for our category?"

    **Inputs**

    | Input | Required | Default | Description |
    | - | - | - | - |
    | `category_id` | Yes | - | Tracked category, from `list_categories` |
    | `start_date` | Yes | - | Window start (inclusive) in `YYYY-MM-DD` format |
    | `end_date` | Yes | - | Window end (inclusive) in `YYYY-MM-DD` format |
    | `view` | No | `distribution` | `distribution`, `brand_share`, or `top_products` |
    | `by_date` | No | `false` | `true` returns a time series. Supported in the `distribution` view only |
    | `metrics` | No | the view's full set | Metrics to return: ones valid for the chosen view |
    | `interval` | No | `day` | Size of each time bucket when grouping by `date`: `day`, `week`, or `month` |
    | `topic_filter` | No | `null` | Narrow to one or more topics |
    | `region_filter` | No | `null` | Narrow to one or more regions |
    | `persona_filter` | No | `null` | Narrow to one or more personas |
    | `prompt_filter` | No | `null` | Narrow to one or more prompts |
    | `tag_filter` | No | `null` | Narrow to one or more tags |
    | `filter` | No | `null` | Filter expression for conditions the other inputs can't express, such as excluding one region or matching either of two topics |
    | `limit` | No | `null` | Top-level groups per page, up to 50 |
    | `cursor` | No | `null` | Pagination token from `info.next_cursor` |

    The `view` input decides what each row represents and which metrics are available.

    | View | Rows | Answers |
    | - | - | - |
    | `distribution` | One row per merchant | Which retailers dominate this category |
    | `brand_share` | One row per merchant and brand | Whose products a retailer shows |
    | `top_products` | One row per merchant and product | What a retailer lists most |

    Each view accepts its own metrics, and the server rejects anything outside the set:

    | View | Metrics |
    | - | - |
    | `distribution` | `merchant_share`, `merchant_share_rank`, `merchant_visibility`, `merchant_visibility_rank` |
    | `brand_share` | `brand_share`, `merchant_share`, `visibility_rank` |
    | `top_products` | `merchant_visibility`, `product_visibility`, `product_rank` |

    **Notes and tips**:

    * This report has no merchant or product filter, so you can't narrow the results to one retailer. Instead, narrow by topic, region, persona, prompt, or tag, then look up the retailer you care about in the returned rows.
    * The `info.view` metadata field names the view the server applied. `view` is optional and defaults to `distribution`, so if the rows don't look like what you expected, check `info.view` to see which view produced them.
  </Accordion>

  <Accordion title="get_shopping_trigger_rate_report">
    Measures how often prompts return shopping mode results. This is the denominator behind the other shopping reports, the assistant can use it to explain a thin or empty result.

    **Example prompts**:

    * "How often do our prompts trigger shopping mode results?"
    * "Which topics trigger shopping mode most often?"

    **Inputs**

    | Input | Required | Default | Description |
    | - | - | - | - |
    | `category_id` | Yes | - | Tracked category, from `list_categories` |
    | `start_date` | Yes | - | Window start (inclusive) in `YYYY-MM-DD` format |
    | `end_date` | Yes | - | Window end (inclusive) in `YYYY-MM-DD` format |
    | `group_by` | No | `null` | Group results by `date`, `topic`, `region`, `persona`, or `prompt` |
    | `metrics` | No | all | Metrics to return |
    | `interval` | No | `day` | Size of each time bucket when grouping by `date`: `day`, `week`, or `month` |
    | `topic_filter` | No | `null` | Narrow to one or more topics |
    | `region_filter` | No | `null` | Narrow to one or more regions |
    | `persona_filter` | No | `null` | Narrow to one or more personas |
    | `prompt_filter` | No | `null` | Narrow to one or more prompts |
    | `tag_filter` | No | `null` | Narrow to one or more tags |
    | `filter` | No | `null` | Filter expression for conditions the other inputs can't express, such as excluding one region or matching either of two topics |
    | `limit` | No | `null` | Top-level groups per page, up to 50 |
    | `cursor` | No | `null` | Pagination token from `info.next_cursor` |

    **Notes and tips**:

    * The default metrics are `total_runs`, `shopping_triggered_runs`, and `trigger_rate_percentage`.
    * Despite its name, `trigger_rate_percentage` is a decimal fraction between 0 and 1, so 0.17 means 17%.
    * Group results by `prompt` or `topic` to see which prompts or topics trigger shopping results most often. Those are the places where shopping visibility is worth optimizing.
  </Accordion>
</AccordionGroup>

## Prompt volume reports

These tools measure demand for a keyword across everything people ask AI platforms. Ask about one keyword at a time; the assistant makes one call per keyword. To see how you appear in the prompts you track, ask for a [visibility report](#get-visibility-report) instead.

| Tool | Usage |
| - | - |
| `get_prompt_volume` | How often people ask AI platforms about a keyword, by week or month |
| `get_prompt_volume_intents` | Why people ask about a keyword, as a share of conversations per intent |

<Note>
  When the assistant reports no estimate for a keyword, that doesn't mean nobody asks about it. Either nothing matched the keyword in that date range, or every slice had two or fewer distinct users and Profound removed it for privacy.
</Note>

<AccordionGroup>
  <Accordion title="get_prompt_volume" id="get-prompt-volume">
    Measures projected weekly and monthly volume for a keyword, by country and platform.

    **Example prompts**:

    * "How many people asked ChatGPT about running shoes last month?"
    * "Is demand for 'project management software' going up this quarter?"

    **Inputs**

    | Input | Required | Default | Description |
    | - | - | - | - |
    | `keyword` | Yes | - | Keyword to measure |
    | `matching_type` | Yes | - | `phrase_match` matches all tokens in any order. `exact_match` also requires the tokens to be adjacent and in the order you typed them, so it returns the same results or fewer |
    | `start_date` | Yes | - | Window start (inclusive) in `YYYY-MM-DD` format |
    | `end_date` | Yes | - | Window end (inclusive) in `YYYY-MM-DD` format |
    | `frequency` | No | `null` | `week` or `month` returns only that frequency. Omit it to get both |
    | `regions` | No | `null` | Narrow to one or more three-letter country codes, such as `USA` |
    | `platforms` | No | `null` | Narrow to one or more platform hostnames: `chatgpt.com`, `gemini.google.com`, or `perplexity.ai` |
    | **Notes**: | | | |

    * Figures come back as weekly and monthly projections, one per country and platform. Weekly figures are dated by the Monday of that week, and monthly figures by the first day of the month. A monthly figure exists only for a calendar month that falls fully inside the date range you ask about, never the current month, so a question about this month gets weekly figures only. A monthly figure isn't the sum of its weeks, because a week that crosses a month boundary is split between the two months. When you need a monthly number, ask for one rather than adding up weeks.
    * A broad question, such as every country and platform over several months, can exceed the 10,000-row limit. The assistant then gets incomplete totals and `info.truncated` set to `true`. Narrow the question to a country, a platform, or a shorter date range to get complete figures.
    * Each new keyword counts toward your organization's limit of 1,000 distinct keywords per UTC day. Asking again about a keyword you already looked up that day doesn't count. If you reach the limit, wait and ask about the same keyword again. Rephrasing it uses more of the allowance.
  </Accordion>

  <Accordion title="get_prompt_volume_intents" id="get-prompt-volume-intents">
    Measures the share of conversations about a keyword that fall under each intent, so you can tell whether people are researching or ready to buy. It doesn't measure how many people ask; `get_prompt_volume` does.

    **Example prompts**:

    * "Are people researching CRM software or ready to buy?"
    * "What intents drive AI conversations about electric bikes?"

    Each intent comes back as a share of the classified conversations, as a fraction from 0 to 1 in `pct_conversation`, so `0.42` is 42%. Shares across all intents add up to 100%. Where an intent has subcategories, each subcategory is its own row (`main_classification` plus `sub_category_classification`), and the share for the main intent is the sum of its subcategories.

    **Inputs**

    | Input | Required | Default | Description |
    | - | - | - | - |
    | `keyword` | Yes | - | Keyword to measure |
    | `matching_type` | Yes | - | `phrase_match` matches all tokens in any order. `exact_match` also requires the tokens to be adjacent and in the order you typed them, so it returns the same results or fewer |
    | `start_date` | Yes | - | Window start (inclusive) in `YYYY-MM-DD` format |
    | `end_date` | Yes | - | Window end (inclusive) in `YYYY-MM-DD` format |
    | `regions` | No | `null` | Narrow to one or more three-letter country codes, such as `USA` |
    | `platforms` | No | `null` | Narrow to one or more platform hostnames: `chatgpt.com`, `gemini.google.com`, or `perplexity.ai` |
    | **Notes**: | | | |

    * Asking about intents doesn't count toward the daily keyword limit, but it shares a burst limit with `get_prompt_volume`. If the assistant is rate-limited, asking about the same keyword again a little later works.
  </Accordion>
</AccordionGroup>

## Traffic reports

These tools are scoped to a tracked domain, not a category. The assistant resolves the domain with [`list_domains`](/mcp/capabilities/discovery-tools#list-domains) first and passes the exact hostname Profound returns.

| Tool | Usage |
| - | - |
| `get_referrals_report` | How many visits did a domain receive from AI engines, and which referrers drove them |
| `get_bots_report` | Which AI crawlers are visiting a domain, and how often |

<AccordionGroup>
  <Accordion title="get_referrals_report">
    Measures visits a domain received from AI engines, such as ChatGPT and Perplexity, over a date range.

    Default metric: `visits`. Useful dimensions include `referral_type`, `referral_source`, and `date`.

    **Inputs**

    | Input | Required | Default | Description |
    | - | - | - | - |
    | `domain` | Yes | - | Tracked domain, using the exact hostname from `list_domains` |
    | `start_date` | Yes | - | Window start (inclusive) in `YYYY-MM-DD` format |
    | `end_date` | Yes | - | Window end (inclusive) in `YYYY-MM-DD` format |
    | `metrics` | No | `visits` | Metrics to return |
    | `dimensions` | No | `null` | Group-by fields, such as `referral_type`, `referral_source`, or `date` |
    | `organization_id` | No | `null` | Disambiguates the domain when the caller belongs to multiple organizations |
    | `filters` | No | `null` | Advanced `{ "field", "operator", "value" }` predicates |
    | `limit` | No | `null` | Top-N row cap. When set, `next_cursor` is always `null` |
    | `referral_source_filter` | No | `null` | Narrow to one or more referrer vendors, such as `openai` |
    | `referral_type_filter` | No | `null` | Narrow to one or more referral categories: `internal`, `referer`, `utm`, or `none` |
    | `cursor` | No | `null` | Pagination token from a previous response |
    | `page_size` | No | `500` | First-page size, up to 10,000 |
  </Accordion>

  <Accordion title="get_bots_report">
    Measures AI crawler activity against a domain over a date range, including bots such as GPTBot and PerplexityBot.

    **Example prompts**:

    * "Which AI crawlers visit our domain?"
    * "Is GPTBot crawling us more since the site update?"

    Default metrics: `count` and `citations`. Useful dimensions include `bot_provider`, `bot_name`, `bot_type`, and `date`.

    **Inputs**

    | Input | Required | Default | Description |
    | - | - | - | - |
    | `domain` | Yes | - | Tracked domain, using the exact hostname from `list_domains` |
    | `start_date` | Yes | - | Window start (inclusive) in `YYYY-MM-DD` format |
    | `end_date` | Yes | - | Window end (inclusive) in `YYYY-MM-DD` format |
    | `metrics` | No | `count`, `citations` | Metrics to return |
    | `dimensions` | No | `null` | Group-by fields, such as `bot_provider`, `bot_name`, `bot_type`, or `date` |
    | `organization_id` | No | `null` | Disambiguates the domain when the caller belongs to multiple organizations |
    | `filters` | No | `null` | Advanced `{ "field", "operator", "value" }` predicates |
    | `limit` | No | `null` | Top-N row cap. When set, `next_cursor` is always `null` |
    | `bot_provider_filter` | No | `null` | Narrow to one or more providers, such as `openai` or `anthropic` |
    | `bot_name_filter` | No | `null` | Narrow to one or more individual bots, such as `GPTBot` |
    | `bot_type_filter` | No | `null` | Narrow to one or more bot categories: `ai_assistant`, `ai_training`, `index`, or `ai_agent` |
    | `cursor` | No | `null` | Pagination token from a previous response |
    | `page_size` | No | `500` | First-page size, up to 10,000 |
  </Accordion>
</AccordionGroup>

## Resources

Profound MCP also exposes read-only MCP resources: static reference material that an MCP client can load into context.

| Resource URI | Audience | Use it for |
| - | - | - |
| `file:///profound/glossary` | Assistant | Compact index of Profound-specific terms to load once per session |
| `file:///profound/glossary/full` | User | Full glossary with definitions and examples, larger than the index |
| `file:///profound/glossary/{term}` | Assistant | Full definition of one glossary term |
| `file:///profound/sentiment-guide` | Assistant | How to choose a sentiment source and read its metrics, filters, and sorting, before calling `get_sentiment_report` |

The `{term}` slot accepts any slug from the glossary index, which includes the metrics and report concepts behind this page's tools:

| Report | Term resources |
| - | - |
| Visibility | `visibility-score`, `visibility`, `mentions`, `share-of-voice` |
| Citations | `citations`, `citation-share` |
| Sentiment | `sentiment`, `aggregated-sentiment-score`, `sentiment-theme` |
| FactCheck | `factcheck-score`, `inaccurate-claim`, `factcheck-theme` |
| Shopping | `shopping-trigger-rate`, `product-visibility`, `merchant-share` |
| Bots | `bot-tracker` |
| Any report | `date-range`, `prompt-volume`, `executions` |