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, the Open source 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 or without an agent key |
Who counts as what
Each request counts in one group:
- People read your docs site in a browser.
- AI agents work for a person: MCP clients, assistants such as ChatGPT-User and claude-code, a search that sends the question of its user, and any call with the
ContextOwl-Agentheader. AI agents count on MCP, the REST API, and the docs site. - Integrations are cowl and the GitHub Action. When cowl runs inside an agent, such as Claude Code, the call counts as that agent.
- Scripts are clients that are not a browser, an AI agent, an integration, or a crawler, such as curl or a Python script. On MCP, only a call without a user agent, or from a hand-driven tool such as curl or Postman, counts as a script.
- Crawlers are search engines and AI crawlers that collect pages in bulk. ContextOwl counts them per day, apart from readers and AI agents.
Tools are integrations and scripts together. The question list and the Not found card show them as one group.
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 each tile compares its total with the period before. Crawler visits also gives the pages that AI crawlers read.
- Reads per day stacks the reads of people and AI agents. AI crawlers count apart. Click Show AI crawlers to add the pages they read to the chart. Hover a column for its numbers, open the data table, or export the chart as PNG or CSV. The data table and the CSV always include AI crawlers.
- Where interest is growing lists the pages, searches, and topics that people or AI agents ask for more than before. See the next section.
- Next steps lists what to do. See Next steps below.
- Most read by people, Top searches by people, and Where readers come from show what people open, search for, and arrive from. See all under the searches opens the question list of people.
- 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, crawlers, and the rest.
- Agents and crawlers, Traffic mix, Reading devices, and Was this page helpful? complete the picture.
- Not found lists the paths that answered not found, and who asked for each one: people, AI agents, crawlers, and tools. The Not found tile counts every miss of the range, and its note gives the misses of people and AI agents, which need a fix.
- AI agents shows what AI agents asked, which questions went unanswered, and which pages agents read. See the next section.
- 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.
Where interest is growing
This section shows what people and AI agents ask for more than before. Click People or AI agents to switch between them. Each side has 3 lists:
- Rising pages lists the pages that more readers or agents opened.
- Rising searches lists the searches of people, and Rising questions lists the questions of AI agents.
- Rising topics groups the wordings of one question, as the Write list of the next steps does.
Pages compare the range with the same number of days before it. Searches and topics compare 30 days at most, because ContextOwl keeps search text for 90 days.
A row rises when all of these are true:
- 5 or more readers or agents asked for it in the range. A reader or an agent counts once a day for each page or search, so a client that asks 50 times a day counts once.
- It has 25% or more readers or agents than in the period before.
- Its score is 2 or more. The score is the rise divided by the square root of the sum of both periods. A rise that is too small to be more than chance stays off the list.
The clearest rise comes first, so a jump from 2 to 20 comes before a jump from 200 to 260. NEW means that nobody asked for it in the period before. Each card states its rule, and each row gives its readers or agents, the change, and its reads or searches. Click View to open a page, Draft to start a page for a search that found no answer, or Hide to remove a row in your own browser.
A list shows not enough data yet when it can't compare:
- The period before had fewer than 10 reads or searches by people, or by AI agents.
- ContextOwl recorded data for only part of the period before. This happens when your docs or the search text started inside that period, or when a long range reaches past the 25 months of daily totals.
When Record search text is off, the search and topic lists say so. Integrations, scripts, and AI crawlers never count in these lists.
The AI agents section
The section counts AI agents only, on MCP, the REST API, and the docs site. A line under the tiles gives the calls of cowl, the GitHub Action, and scripts, which don't count as AI agents.
- Who asked splits the section into agent keys, agents without a key, and the agents that signed-in readers connected. Each group shows its searches. Traffic from before ContextOwl recorded who asked counts in All only, and a note says when the range holds such traffic.
- What agents ask lists the top questions. Each row names the agents and the Who asked groups, and counts the unanswered searches and the agent reports.
- Unanswered lists the questions that the docs didn't answer. A question counts when no search for it found a page that the same agent opened within 30 minutes. A gap report from the agent counts too. Click Draft to start a page with the question as its title.
- Most read by agents, Agents, and Agent keys show the pages that agents read next to human reads, and the agents and keys that called in.
When no AI agent searched or read in the range, the section explains how to connect one.
The question list
See all questions opens Admin > Analytics > Questions. It lists every question of the range, 100 at a time.
- Filter by 7, 30, or 90 days, by workspace, and by AI agents, People, or Tools. For AI agents, you can also filter by Who asked.
- Turn on Only unanswered to list only the questions with an unanswered search or an agent report.
- Each row gives the searches, the unanswered searches, the agent reports, who asked, and the last day. Click Draft to start a page with the question as its title.
- Click Export CSV to save up to 10,000 questions as a spreadsheet. A cell that starts like a formula, such as =, gets a leading quote, so the spreadsheet shows it as text.
Question text is kept 90 days, so the list covers 90 days at most.
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 no match, or when the reader or the agent opened none of the top 3 results within 30 minutes. When an agent sends one question with several searches, the question is answered when one of them led to a read. The searches of integrations and scripts don't count. 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 AI agents followed to a page that doesn't exist. A path that only crawlers and tools asked for stays off the list, and the reason line of each row shows the full split. 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.
What search learned
Search learns from use. What search learned lists the searches that changed the order of search, with the page that people and AI agents opened after each one, and how many of them did. The card shows what search knows now, so it doesn't follow the range.
- A search counts when it found something and comes from a person or an AI agent. Integrations, scripts, and crawlers don't count, and neither do readers who send Do Not Track or Global Privacy Control.
- A person's search counts for the first result opened within 30 minutes and before the next search. An agent's search counts for the first 3 results read. A page that the search didn't return gets no credit.
- An agent key counts once. A reader counts once a day, because ContextOwl keeps no reader ID across days. An agent without a key counts only when ContextOwl verified it.
- A page moves after 3 keys, or 3 readers on one day, open it after similar searches. Keys and readers add up.
- Only BETA and STABLE pages learn. A page with a password and an encrypted page never learn.
- A signal loses half its weight every 30 days, and the boost stops growing at 10 fresh searchers. Learning only reorders the results of a search. It never adds a page that the search didn't find.
- Similar searches match by their words, and by meaning when semantic search is set up.
- The palette, search_docs, semantic_search, and the REST search learn. The exact text order of the palette toggle leaves learning out.
To turn learning off for a workspace, or to reset what it learned, open Admin > Settings > Publishing. Search learning needs search text, so it stops when Record search text is off.
Weekly report
Editors and admins get a weekly email with the reads of the week and of the week before, up to 3 rising topics or pages, and up to 3 lines each of Write, Update, and Fix. It covers Monday to Sunday in UTC. A week in which only AI crawlers visited sends no email. 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 and agent questions have tokens and email addresses removed, and they're deleted after 90 days. To stop saving them, turn off Record search text in Admin > Settings > API.
- Readers who send Do Not Track or Global Privacy Control aren't counted.
- Search learning keeps the words of a search and the page opened after it, for the same 90 days. It counts a reader without a key by a hash of the network of the IP address for one day, and it keeps no reader ID. Turning off Record search text deletes what it learned.
- 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 |
| List every question | REST only: listQuestions | cowl analytics questions |
The report includes growth, and the next steps include rising, for people and for AI agents apart.
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.