Metrics
What each figure the Heading MCP returns means, and the rules every figure follows
Every figure the Heading MCP returns is computed by the same code as the dashboard page that shows it, so a figure here is the figure that page shows for the same brand, days and filters. This page defines each one in Heading's own terms.
Rules every figure follows
Days are UTC. There are no user time zones anywhere in Heading's data. A day is a UTC calendar day, written YYYY-MM-DD, and startDay and endDay are both included in a range. Leave them out for the last 28 days. The exceptions are list_changes (30 days) and get_traffic_report, whose Google Analytics, leads and Search Console figures default to 30 days and whose crawl activity defaults to 28.
A range cannot open before daily tracking did. Daily collection starts on the day the brand's subscription starts. Before that, Heading took point-in-time snapshots over a different prompt set, and joining the two would read as a collapse that never happened. So a range that starts earlier comes back shorter, with a note naming the day it opens on. That is a shorter history, not missing data.
Free and lapsed brands are not reachable here. Through the MCP every brand is on a paid plan or a trial. Heading's own agent, which runs the same tools inside the dashboard, can also read a brand that never paid (its single as-of day, with no comparison and no trend) and a lapsed one (up to its last collected day); the answer says so when it does.
Null is not zero. A figure Heading did not measure is null, and the answer says why, in nullReasons or a note: no answer in the range, no answer that reports its citations, no answer that names the brand, a source that is not connected. A measured zero is 0. Read the reason before you state the figure.
Notes come first. Every report answers notes stating each default, clamp and limit that shaped its figures. Read them before you repeat a figure.
Scores mean the active prompt set. Visibility is measured over the prompts being tracked on each day, the AI platforms being tracked and the competitors being tracked. When a figure moves, list_changes tells you whether the measurement changed rather than the performance.
Unbranded by default. The visibility, perception and sources reports open on unbranded prompts (the prompts that do not name the brand), as the dashboard pages do. Pass queryType: "all" for every prompt. list_prompts and list_answers default to all. get_objective_measure has no default: it requires queryType.
Visibility
get_visibility_report returns these nine figures for the summary and for every row of a breakdown. list_prompts carries the same figures for each prompt on its latest measured day.
| Figure | What it means |
|---|---|
mentionedPct (Mentioned %) | The answers that name the brand, as a share of every measured answer. Each answer counts once. |
citedPct (Cited %) | The answers that cite one of the brand's own sites, as a share of the answers that report their citations. |
mentionShare (Mention share) | The answers that name the brand, as a share of every naming of a tracked brand in the same answers. Each brand counts once per answer, however often it is repeated. |
citationShare (Citation share) | The distinct pages cited from the brand's sites, as a share of every distinct page cited in the same answers. |
avgMentions (Avg. mentions) | How often the brand's name, aliases or domain appear per measured answer. An answer that does not name it counts as zero. |
avgCitations (Avg. citations) | The distinct pages cited from the brand's sites per answer that reports its citations. |
responses | The measured answers in the row: one prompt asked on one platform on one UTC day. |
averageRank | The brand's average rank in the answers that name it. See Rank. |
avgSentiment | The average sentiment toward the brand in the answers that name it and were scored, from -1 (negative) to 1 (positive). |
A row with no answers states responses: 0 and every figure as null.
Rank
Rank counts tracked brands only: the brand and its tracked competitors. 1 is named first, and brands named at the same point in an answer share a rank. A business you do not track never counts, so a rank can read better than the brand's place among every name in the answer. An answer that does not name the brand has no rank (null), and an average rank is taken over the answers that name it. list_answers and get_answer give the rank in each answer, beside the rank of each tracked competitor it names.
The objective measure
get_objective_measure returns the figure a metric key result is judged on: visibility on the latest measured UTC day for one scope: a required queryType, and optionally a market and tags. It is one day's figure, so it does not compare with a range from get_visibility_report.
Perception
get_perception_report answers what AI says about the brand, where the visibility report answers how often AI names it. Perception is measured on dimensions: ten qualities every brand is judged on (such as service, value for money and trustworthiness), plus qualities generated for your category from your own answers. Every tracked brand is judged on the same dimensions, so a quality a competitor holds and you do not shows as a gap.
The summary, and every brand row, carries:
| Figure | What it means |
|---|---|
responses | Assessed answers: the answers in the range that name the brand and were assessed for perception. |
sentimentPct (Overall sentiment) | The mean sentiment of those answers on a 0 to 100 scale: 0 fully negative, 50 neutral, 100 fully positive. |
sentimentMean | The same mean on its own scale, from -1 to 1. |
focusedLed (Focused dimensions led) | How many focused dimensions the brand leads: its rate is at or above every other compared brand's. A tie counts as leading. |
focusedTotal | How many dimensions are focused, up to 10. |
strongestDimension (Strongest quality) | The focused dimension AI describes the brand with most often. |
compared | Whether the brand reached 10 assessed answers in the range, the minimum for any comparison. |
Every dimension row carries:
| Figure | What it means |
|---|---|
ratePct | The share of the answers the brand was assessed in that depicted it this way. |
mentions | The assessed answers that depicted the brand this way. |
responses | The assessed answers the rate is taken over. |
bestCompetitorRatePct, bestCompetitor | The highest rate on this dimension among the other tracked brands that reached the comparison minimum, and whose it is. |
gapPoints | The brand's rate minus the best competitor's, in percentage points. Negative means behind. |
leads | true when the brand's rate is at or above every other compared brand's. |
Not measured is not 0%. A brand with fewer than 10 assessed answers in the range is not compared: its rates are null with the reason not_measured. Focus changes emphasis, never what is measured: every dimension is listed, focused or not. A retired dimension stays readable over the days before it retired.
Sources
get_sources_report reads the sources AI cites in answers to the brand's tracked prompts. A cited source is a domain or page an AI answer named as its source. It is not a backlink and not traffic.
| Figure | Level | What it means |
|---|---|---|
usedPercent (Used %) | domain | The measured answers that cite the domain at least once, as a share of the measured answers. |
avgCitations (Avg. citation) | domain | How many times the domain is cited per answer that cites it. |
citationRate (Citation %) | url | The answers that cite the page, as a share of the answers that report their citations. |
retrievalRate (Retrieval %) | url | The answers that retrieved the page, as a share of the answers that report what they retrieved. |
citationCount, retrievalCount | url | The answers that cite or retrieved the page. |
Every row also says whether the source is one of your own sites (domainType: "own", otherwise ugc, editorial or corporate) and carries two flags:
gapistruewhen the source is cited in answers that name a tracked competitor and in none of the answers that name you. A gap is co-citation in AI answers: it says the source appears beside a competitor's name, not what the source's own pages say about anyone.gapCompetitorsnames those competitors.risingistruewhen the source's citation rate over the range rose against the same number of days just before.
With queryType: "all" and no tag or market filter, domain figures come from Heading's monthly source statistics, as on the Sources page, so a month is read whole; the notes say so when it applies.
Answers
list_answers and get_answer return the collected answers themselves. Each answer is one prompt asked on one platform, counted on one UTC day. For each answer: whether it names the brand, the brand's rank among tracked brands (null when not named), the brand's sentiment (null when not scored), the tracked competitors it names with their ranks, and the sources it cites. Every score above is computed from these answers.
Traffic
get_traffic_report returns the Traffic page. Its figures come from sources you connect, and each is stated in that source's own units:
- Google Analytics: sessions, leads, revenue and conversion rate, per Google Analytics.
- Search Console: clicks, impressions, CTR and average position, per Google Search Console. A click is not a session.
- Leads: verified leads from each connected source, and the lead webhook's state.
- AI crawler activity from your own server logs: requests by category (Search, Retrieval, Training), the share verified as coming from the operator the crawler claims, what your site answered, the most fetched pages and the pages no search crawler has fetched.
Log entries, Analytics sessions and Search Console clicks are different units and are never added together. A source that is not connected answers null with a reason, never 0.
Agent readiness
get_agent_readiness measures the brand's own website rather than what AI says about it: whether the machines that produce AI answers can find, read and use the site. It returns a 0 to 100 score with a grade from A+ to F, four weighted layers (Discovery 20, Access 30, Usability 40, Payments 10), the fixes ranked by the points a full pass would add, and every probe with what it fetched and observed. A brand never measured answers null, and a run that could not reach the site has a null score, never a clean result.
Confidence
list_context_docs returns Confidence: how well Heading understands the business, as last assessed from the brand's context documents. It is a score and a band, with a coverage grade for each dimension, weakest first, and the questions that would deepen it. When nothing has been assessed the score is null with the reason, never 0.