> For the complete documentation index, see [llms.txt](https://docs.airops.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.airops.com/mcp-server/tools-and-support/tools/analytics-and-reports.md).

# Analytics & Reports

Query page performance, agent traffic, AI visibility analytics, and reports.

Query page performance, agent traffic, AI visibility analytics, and reports.

See [plan access](broken://pages/GlhqboJgu5fTfPseY3y1#plan-access) and [query options](broken://pages/GlhqboJgu5fTfPseY3y1#query-options) for shared requirements.

## Page Analytics

### `list_pages`

List pages with AEO, Google Search Console, and GA4 metrics.

**Requires:** `brand_kit_id`

**Returns:** For each page: URL, folder path, primary keyword, and metrics:

* **AEO:** citations\_count, citation\_rate, prompts\_count, and trends
* **GSC:** clicks, impressions, ctr, position, and trends
* **GA4:** traffic, sessions, engagement, average\_session\_engagement, and trends
* **Agent Analytics:** `user_browse` (AI Agent Visits), `ai_training` (Training Crawls), and `ai_search` (Web Search Crawls)

Agent Analytics must be connected first. Its three counts support filtering and sorting for the selected dates, without change variants. Use `list_aeo_agent_analytics` for Total Crawls and daily breakdowns.

| Parameter         | Values                                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| **Filters**       | Any metric field, url, folder\_name, primary\_keyword, session\_source, session\_medium                |
| **Sort**          | All metric fields, url, folder\_name                                                                   |
| **Smart filters** | almost\_page\_one, losing\_clicks, rankings\_slipping, losing\_ai\_visibility, citation\_rate\_decline |

**Smart filters** (use instead of manual filtering):

| Filter                  | Description                                  |
| ----------------------- | -------------------------------------------- |
| `almost_page_one`       | Pages ranking #11-20 (quick wins for page 1) |
| `losing_clicks`         | Declining clicks with stable position        |
| `rankings_slipping`     | Position declining over time                 |
| `losing_ai_visibility`  | Losing AEO citations                         |
| `citation_rate_decline` | Losing AI authority with stable SEO          |

***

### `create_page`

Add a page to a Brand Kit's AEO pages. AirOps normalizes the URL, verifies that it belongs to the Brand Kit's configured AEO domain, and requires it to be unique within that Brand Kit.

**Requires:** `brand_kit_id`, `url`

**Returns:** Page ID, Brand Kit ID, AEO domain ID, normalized URL, tracked status, creation timestamp, and a confirmation message.

Confirm the URL and Brand Kit with the user before creating the page. Verify the result with `list_pages` filtered by URL. This adds the page to AirOps; it does not publish content to a CMS.

***

### `get_page_details`

Get detailed metrics for a specific page.

**Requires:** `id`

**Returns:** URL, folder, primary keyword, citation share, citation rate, unique cited questions count, GSC metrics (clicks, impressions, position, CTR), and all trends.

| Parameter      | Values                 |
| -------------- | ---------------------- |
| **Date range** | start\_date, end\_date |

***

### `get_page_prompts`

Get AI prompts that cite a specific page.

**Requires:** `brand_kit_id`, `web_page_id`

**Returns:** Prompt ID, text, keyword, topic\_id, volume, total\_answers, answers\_with\_citations, citation\_rate, mention\_rate, and trends.

| Parameter      | Values                                     |
| -------------- | ------------------------------------------ |
| **Filters**    | providers, countries, personas, topic\_ids |
| **Includes**   | topic                                      |
| **Date range** | start\_date, end\_date                     |

***

## Agent Analytics

### `list_aeo_agent_analytics`

List daily bot requests to the Brand Kit's tracked pages. [Connect Agent Analytics](broken://pages/QZKzkZuRhzJ2Gh55j3RG) before querying this data.

**Requires:** `brand_kit_id`

**Returns:** Rows containing `date`, `platform`, `crawl_type`, and `count`. The crawl types are `ai_search`, `ai_training`, `user_browse`, and `other`. Rows with no requests are omitted.

| Parameter      | Values                                                                |
| -------------- | --------------------------------------------------------------------- |
| **Date range** | `start_date`, `end_date`                                              |
| **Filters**    | `platform`, `crawl_type`, or a single `web_page_id` from `list_pages` |
| **Sort**       | `date` (default), `count`, or `-count`                                |
| **Pagination** | `page`, `per_page` (25 by default, 100 maximum)                       |

Read every page before summing counts. The Agent Analytics **Total Crawls** summary counts search and training crawls for tracked AI engines. The **Pages** table's Total Crawls counts every platform and crawl type for that page. Use the [API calculation guide](broken://pages/9d498HbYABfQQCI5bVbU#agent-analytics) for the exact engine set, chart recipes, and date-boundary behavior.

## Analytics

### `query_analytics`

Query analytics with flexible metrics, dimensions, and filters. BI-style interface for custom analysis.

**Requires:** `brand_kit_id`, `metrics`

**Returns:** Query results with requested metrics grouped by dimensions, plus metadata.

**Metrics:**

| Metric               | Description                              |
| -------------------- | ---------------------------------------- |
| `mention_rate`       | % of answers mentioning brand (0-100)    |
| `share_of_voice`     | Brand mentions vs competitors (0-100)    |
| `citation_rate`      | % of answers citing brand domain (0-100) |
| `citation_share`     | Brand citations vs all citations (0-100) |
| `citation_count`     | Absolute citation count                  |
| `sentiment_score`    | Average sentiment (0-100)                |
| `average_position`   | Mean rank in answer lists                |
| `answer_count`       | Total answers analyzed                   |
| `first_mention_rate` | % where brand is mentioned first (0-100) |

**Dimensions** (max 3):

| Dimension         | Description                   |
| ----------------- | ----------------------------- |
| `date`            | Group by time period          |
| `provider`        | Group by AI provider          |
| `topic`           | Group by tracked topic        |
| `competitor`      | Group by competitor           |
| `country`         | Group by region/country       |
| `persona`         | Group by customer persona     |
| `domain`          | Group by cited domain         |
| `domain_category` | Group by citation source type |

| Parameter      | Values                                                   |
| -------------- | -------------------------------------------------------- |
| **grain**      | daily, weekly, monthly, total (default: total)           |
| **Date range** | start\_date, end\_date (default: last 7 days)            |
| **Filters**    | providers, topics, countries, personas, brand\_mentioned |
| **Limit**      | rows per request (default 100, range 1–5,000)            |
| **order\_by**  | custom sort (e.g., "citation\_count DESC")               |

#### Dates, grouping, and sorting

Use ISO dates in `YYYY-MM-DD` format. `start_date` defaults to seven days ago and `end_date` to yesterday. An end date of today or later is changed to yesterday; `meta.end_date` reports the date used. A start date after yesterday, an invalid date, or a reversed range returns an error.

| Grain     | Maximum days from start date to end date |
| --------- | ---------------------------------------- |
| `daily`   | 120                                      |
| `weekly`  | 180                                      |
| `monthly` | 365                                      |
| `total`   | 365                                      |

Include the `date` dimension to split results into time buckets. Weekly buckets start on Monday and monthly buckets on the first of the month, so boundary buckets can be partial and their labels can precede your start date.

The `domain` and `domain_category` dimensions support citation metrics and `answer_count`. The `theme` dimension supports `sentiment_score` and `answer_count`. You cannot combine `competitor` with `sentiment_score`. If omitted, `countries` defaults to `["US"]`.

For `order_by`, use comma-separated requested metrics or dimensions followed by `ASC` or `DESC`, such as `citation_count DESC, date ASC`. Sorting by an unrequested field returns an error. Use `offset` to paginate; negative offsets become zero, and limits outside 1–5,000 are adjusted to the nearest bound.

***

### `get_sentiment_theme_answers`

Get the answers behind a sentiment theme so you can inspect source answer text and examples for that theme.

**Requires:** `brand_kit_id`, `sentiment_theme_id`

**Optional fields:** `start_date`, `end_date`, `providers`, `countries`, `topic_ids`, `persona_ids`, `page`, `per_page`

***

### `analytics_chart`

{% hint style="info" %}
**Interactive App:** This tool renders a chart in the conversation. Available in **Codex through the AirOps plugin, Claude Web, and Claude Desktop**.
{% endhint %}

Query analytics and display as an interactive chart. Returns data with a UI reference for visualization.

**Requires:** `brand_kit_id`, `metrics`

**Returns:** Chart data with interactive visualization rendered in the conversation.

| Parameter       | Values                                                         |
| --------------- | -------------------------------------------------------------- |
| **chart\_type** | line, bar, pie, area (default: line)                           |
| **metrics**     | Same as query\_analytics                                       |
| **dimensions**  | Same as query\_analytics (max 2 for line charts with grouping) |
| **grain**       | daily, weekly, monthly, total                                  |
| **Date range**  | start\_date, end\_date                                         |
| **Filters**     | providers, topics, countries, personas, brand\_mentioned       |
| **title**       | Optional chart title                                           |

**Constraints:**

* Only metrics from the same scale can be plotted together (percentage, count, or position)
* Area and bar charts support single metrics with single dimensions
* Line charts support up to 2 dimensions but only single metric when using 2

***

## Reports

### `list_reports`

List saved analytics reports.

**Requires:** `brand_kit_id`

**Returns:** Report ID, name, created\_at, updated\_at.

| Parameter    | Values                         |
| ------------ | ------------------------------ |
| **Filters**  | name                           |
| **Sort**     | name, created\_at, updated\_at |
| **Includes** | modules                        |

***

### `get_report`

Get a specific report by ID.

**Requires:** `brand_kit_id`, `id`

**Returns:** Report ID, name, timestamps. With `includes: ['modules']`, returns full module configurations.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.airops.com/mcp-server/tools-and-support/tools/analytics-and-reports.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.