SKILL.md

---
name: reviewing-analytics
description: Use when reporting on docs traffic, search quality, AI assistant usage, feedback, or billing-period usage through the Mintlify Admin MCP — questions like "what are people searching for", "which pages are popular", "how many chat messages this month", or "what gets zero results".
---

# Reviewing Analytics

## Overview

All analytics live in the code-mode `analytics` namespace (`execute_code`, no checkout, all read-only, scope `analytics:read`). Most methods take `dateFrom`/`dateTo` as ISO or `YYYY-MM-DD` strings; list endpoints are cursor-paginated.

**REQUIRED BACKGROUND:** the `using-code-mode` skill covers return semantics and `{ subdomain }` targeting.

## Method map

| Question | Methods |
|----------|---------|
| Overall traffic/engagement | `getInsights({})`, `getKpi`, `getPopularPages({ dateFrom, dateTo, trafficSource? })`, `getReferrals`, `getTopAgents` |
| What are people searching | `getSearchAnalytics({ dateFrom, dateTo, limit?, cursor? })`, `getTotalSearches`, `getUniqueSearchQueries`, `getSearchTimeSeries`, `getSearchClickThroughRate` |
| Search gaps | `getZeroResultSearches`, `getZeroResultSearchCount` |
| MCP search traffic | `getMcpSearchAnalytics`, `getMcpSearchTimeSeries`, `getMcpSearchTotalSearches` |
| AI assistant usage | `getAssistantAggregate`, `getAssistantCallerStats`, `getAssistantUsageSummary`, `getChat` (conversation list) |
| Reader feedback | `getFeedback` (thumbs aggregate), `getDetailedFeedback`, `getDetailedFeedbackSummary`, `getDetailedFeedbackById` |
| Billing-period usage | `getUsageSummary({ usageType })`, `getUsageHistory` — usageType: `CHAT_MESSAGE`, `PDF_PAGE`, `TRANSLATION_TOKEN_INPUT`, `TRANSLATION_TOKEN_OUTPUT` |

`getUsageSummary` takes only `usageType` (no dates) and always reports the **current billing period** — quota, period usage, and remainder. `getAssistantUsageSummary` is the assistant-specific view of the same billing meter, while `getAssistantAggregate`/`getChat` are date-ranged analytics windows — use the usage methods for "how much of my quota", the analytics methods for "what happened between these dates".

`trafficSource` on traffic methods is `'all' | 'ai' | 'human'` — useful for splitting agent vs human readership.

## Example: monthly search-quality report

```
const range = { dateFrom: '2026-06-01', dateTo: '2026-06-30' };
const top = await analytics.getSearchAnalytics({ ...range, limit: 50 });
const zero = await analytics.getZeroResultSearches(range);
const ctr = await analytics.getSearchClickThroughRate(range);
({ top, zero, ctr });
```

## Common mistakes

- Guessing parameter names — `getChat` uses `currentDateFrom`/`currentDateTo` (not `dateFrom`); verify with `search_code_operations { namespace: 'analytics', query: ... }`.
- Ignoring `cursor` on list endpoints and reporting a truncated picture.
- Requesting huge ranges in one call and hitting `truncated: true` — page or narrow the range.
- Comparing AI vs human traffic without setting `trafficSource`.