Overview
What Notable measures, how to read its numbers, and the ways to get them out of the app.
Notable asks AI assistants the questions your customers ask, many times over, and reads every answer. It tells you how often each assistant names you, recommends you, cites your site and puts you among the first three businesses it names, side by side with your competitors, and what to do next to be recommended more.
These docs are for getting that data out of the app: into your own scripts and dashboards with the REST API, or into an AI assistant such as Claude or Cursor with the MCP server.
Concepts
- Brand: a business you track, with its website, market (country and language) and the competitors you compare it with. Brands live in workspaces; you see the brands of every workspace you belong to.
- Intent: one question your buyers ask an AI assistant, such as "best accounting software for freelancers". Each brand tracks several.
- Engine: one AI assistant. Today:
chatgpt,aio(Google AI Overviews),ai_mode(Google AI Mode),gemini,perplexity,copilotandclaude. - Action: one suggested next step to be recommended more, worked out from the answers and from your site, with the strength of the evidence behind it.
The four metrics
Every figure is a share of valid answers over the latest 28 days: answers that were collected and not empty.
| Metric | The answer… |
|---|---|
answer_share | names the business |
pick_rate | recommends the business, backed by a sentence that says so |
citation_rate | cites a page on one of the business's own domains |
top_three_rate | names the business among the first three businesses it names |
Reading the numbers
Each rate comes with its 95% interval and the number of answers behind it. When there are too few answers to say anything useful, there is no number, only the reason. A change against the previous four weeks is reported only when it is statistically significant (p < 0.05) and at least 5 percentage points; anything smaller is normal variation. The methodology explains how every number is made.
Access and keys
The API and the MCP server use the same personal API key, and see exactly what you see in the app: the same brands, with the same role. Create one under Account → API and MCP keys (https://www.heynotable.com/account#api-keys). The key is shown once, so copy it then.
- Send it as
Authorization: Bearer ntb_…on every request. - At most 10 active keys per person, and 120 requests a minute per key.
- A key stops working when you revoke it, when you leave a workspace (for that workspace's brands), or when your account is deleted.
Treat a key like a password: it reads everything you can read, and can mark actions done on brands you can edit.
Next
- REST API: endpoints, parameters and response shapes.
- MCP server: connecting Claude Code, Claude Desktop, Cursor and other clients.