Metrics and methodology
How Doclight defines citation share, citation rate and the other numbers it reports, what each denominator is, and what the numbers do not claim.
Every number Doclight reports has a defined scope. Two metrics that look similar can have different denominators, so a
report always names the scope it used. This page summarises the definitions; the report payload also carries
metric_version so a stored report is never silently reinterpreted under newer definitions.
What is being measured
Doclight calls provider APIs with your tracked questions and parses the answers. The results describe those API-model responses. They are not equivalent to what ChatGPT, Claude, Perplexity, Gemini or a search engine shows a person in their consumer app, which may use different models, tools, personalisation and retrieval.
Which providers were actually measured in a window is reported separately from which providers Doclight integrates with:
provider_coverage lists each provider with its integration status and whether it was measured.
Core metrics and their denominators
| Metric | Denominator | Notes |
|---|---|---|
total_citations_extracted | All citations to any domain the parser found, tracked or not | Includes unrelated third-party domains. |
brand_citations | Citations to the brand's own normalised domain | |
citation_share | Brand citations ÷ (brand + tracked-competitor citations) | null when that denominator is zero. The scope is stated in denominators.citation_share. |
brand_citation_rate | Successful responses with at least one brand citation ÷ all successful responses in the window | A response denominator, not a citation denominator. Failed and pending responses are excluded. null with no successful responses. |
| Per-provider share of voice | Brand citations ÷ all domains cited within that one provider | A different scope again; a provider that surfaces mostly unrelated sources can show a low value even when you lead your competitors. |
Why 5 citations can be 100% share
If an answer set contains five citations, only one of them to your brand, and none of the other four domains is a tracked
competitor, then the brand-versus-competitor denominator is just your one citation, so citation_share is 100%. Both
numbers are correct under their own definition, which is why the scope is always disclosed next to the value.
Comparisons
Period-over-period changes carry a comparison field instead of a bare percentage:
no_baseline: nothing comparable in the prior window. Shown as a first measurement, never as a percentage.no_change: current equals previous, including both zero.new_from_zero: a measured zero became positive.percent_changeisnull; there is no finite percentage.increase/decrease: the previous value was non-zero, sopercent_changeis a normal relative change.
Citation share is already a percentage, so its change is expressed in percentage points (20% → 25% is +5pp).
Data sufficiency
Each window reports how many distinct questions were evaluated and how many responses were attempted, successful, failed
and pending. sufficiency is one of no_data, sparse (fewer than five successful responses) or sufficient, with a
plain-language explanation. There is no numeric "confidence score". Small denominators deserve caution, most of all in
market-scoped views.
Mentions, citations and crawler visits
- A citation is a domain found in a provider's answer. Its
mention_typerecords only how it appeared:direct_link(a full URL) orreference(a bare domain-shaped string). It does not say whether the answer recommended you. - A crawler observation is a visit by a known AI crawler, reported by your site integration. Visits are classified from the user agent, and crawler identity is not verified.
- A crawler visit is not a citation, and a citation does not mean a crawler visited. An empty crawler report means "no observations received", not "crawlers are blocked": the integration may be missing or no crawler may have visited.
Interface language versus research language
The language you use the dashboard in does not change what is measured. Each tracked question carries its own research language and target country, set when the question is created (or inherited from the brand's first target market).
- Language and country are applied as prompt conditioning, a short system instruction telling the provider which language to answer in and where the asker is located. It is not geolocated execution: requests do not originate from that country.
- A market-scoped figure is a subset with a different denominator, so it is not comparable with the brand-wide figure.
- History is not relabelled. Editing a question's language or country creates a new question version; past responses keep the version they ran under.
Recommended-action ordering
Actions are ordered deterministically by priority group, evidence strength, page importance, affected pages, effort and freshness. The order is not a probability of success. The evidence support score explains how much observable evidence backs a finding and does not affect ordering.