# Analytics

Analytics shows how people and AI agents use your docs, and what to write, update, or fix next. Open **Admin > Analytics**. It needs a paid plan or the free trial. Viewers, editors, and admins can open it.

## What ContextOwl counts

ContextOwl counts every read on the server, on every channel:

| Channel | What it covers |
| --- | --- |
| Docs pages | People who read your docs site, and agents that fetch its pages |
| Markdown pages | Agents that read the Markdown of a page |
| llms.txt | Agents that load the index or the full text |
| Changelog feeds | The RSS feed and the Markdown changelog |
| OpenAPI files | Downloads of the public OpenAPI spec |
| MCP | Agents that call the MCP endpoint, with or without a key |
| REST API | Calls to the REST API with an agent key |

Each read counts as a person, an AI agent, an integration such as cowl, or a script. Search engines and AI crawlers that collect pages in bulk are counted per day, apart from readers.

## The analytics page

Pick 7, 30, or 90 days or 12 months, and one workspace or all of them.

- **Signals** give the totals of the range and compare them with the period before.
- **Reads per day** stacks the reads of people and AI agents. Hover a column for its numbers, open the data table, or export the chart as PNG or CSV.
- **Next steps** lists what to do. See the next section.
- **Most read by people**, **Top searches**, and **Where readers come from** show what people open, search for, and arrive from.
- **From AI assistants** counts the people who followed a link in an answer of ChatGPT, Perplexity, Claude, Gemini, and other assistants.
- **How content is reached** splits each channel into people, AI agents, and the rest.
- **Agents and crawlers**, **Not found**, **Traffic mix**, **Reading devices**, and **Was this page helpful?** complete the picture.
- **Agents** lists what agents asked over MCP and the REST API, which questions went unanswered, and which pages agents read.
- **Customer accounts** lists the reads of signed-in guests by the domain of their email address, so you see which customers use a private portal. The reads of agents that a guest connected with their sign-in count for the same domain. It never names a person.

## Verified agents

Anyone can send the user agent of GPTBot or ChatGPT. ContextOwl checks the claim in 2 ways:

- It compares the IP address with the ranges that OpenAI, Anthropic, Perplexity, Google, and Microsoft publish for their crawlers.
- It checks a Web Bot Auth signature when the agent sends one, against the keys that the agent publishes. A signed agent that browses with a browser user agent, such as the ChatGPT agent, then counts as that agent and not as a person.

**Agents and crawlers** shows how many hits of each agent were verified, and the **AI agent reads** tile shows how many reads were verified. A hit that no check proves still counts, as claimed.

## Next steps

Next steps turns the data into work in 3 lists:

- **Write** lists the questions that your docs didn't answer. A search counts as unanswered when it found nothing, or when the reader or the agent opened none of the top 3 results within 30 minutes. Agents can also report a question. The wordings of one question are grouped into one topic, and with semantic search set up, questions that mean the same are grouped too. Click **Draft** to start a page with the question as its title.
- **Update** lists pages that readers voted unhelpful, and pages that people and agents read often while nobody changed them for 180 days. Click **Open** to edit the page.
- **Fix** lists article links that people and agents followed to a page that doesn't exist. Click **Redirect** to send the old link to the closest page, or **Draft** to write the missing page.

Each row says why it's on the list. **Hide** removes a row in your own browser.

## Weekly report

Editors and admins get a weekly email with the reads of the week and up to 3 lines each of Write, Update, and Fix. It covers Monday to Sunday in UTC. To stop it, turn off **Weekly docs report** in the email settings of your account.

## Privacy

- Readers get no cookie and no stored ID. ContextOwl hashes each reader with a salt that changes every day, and it deletes the old salt.
- Referrers are kept as domains only. Raw IP addresses and user agents are never stored. For signed-in guests, only the domain of the email address is kept.
- Search text has tokens and email addresses removed, and it's deleted after 30 days. To stop saving it, turn off **Record agent search queries** in **Admin > Settings > API**.
- Readers who send Do Not Track or Global Privacy Control aren't counted.
- Raw events are kept 90 days, and daily totals 25 months.

## For agents

An agent key with the analytics.read permission reads the same data over MCP, the REST API, and cowl:

| Task | MCP tool | cowl |
| --- | --- | --- |
| Read the report | get_analytics_report | cowl analytics report |
| Read the next steps | get_content_insights | cowl analytics next |
| Read what agents asked | agent_insights | cowl insights |

Any agent that can search your docs can report a question that the docs didn't answer, with report_content_gap or `cowl analytics gap`. This also works without a key on the public MCP endpoint of your docs site. See [Agent Access](/docs/contextowl/agent-access).