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.