# Citation Metrics Glossary > Canonical definitions for citation-tier classification and the three citation metric > families: **Citation Rate**, **Citation Coverage**, and **Citation Share**. > > This is the source of truth for what every citation number Senso reports means. Each > metric below is defined by its numerator, its denominator, and the grain it counts at. > Where a field name in the API differs from the name used here, this file wins on > meaning and the API reference wins on spelling. --- ## Canonical definitions ### The unit: an *answer* (prompt-run) A **prompt-run answer** (also *run*, *question run*, *observation occurrence*) is one execution of one prompt against one provider/model/location on a given day, for one owner. Citation rates count **distinct answers**, never individual citations/URLs. ### Citation tiers (classify each cited URL by its domain) Every **cited** URL is classified into exactly one mutually-exclusive tier: | Tier | Product name | Stored value | Definition | |-----------|--------------------|--------------|------------| | Primary | Primary / Owned | `primary` | The URL's **domain** is one of the org's own websites (`org_websites`), or a subdomain of one. | | Tracked | Tracked | `tracked` | The **URL** matches one of the org's tracked sources (`org_tracked_sources`, tier `tracked`) at that rule's own scope — whole domain, host, path prefix, or exact URL — most-specific-match-wins. | | External | External | `secondary` | Anything else (third-party). | Note the grain difference: **owned is domain-grain, tracked is URL-grain.** Tracking one page tracks that page, not its whole domain. `rollups.org_webpage` carries the exact per-page tier; `rollups.org_domain` is domain-grain and reports the strongest tier observed under that domain. - **"External" is the product-facing name for the `secondary` tier — they are the same thing.** Do not introduce a fourth concept. - The three tiers **partition citations** (each cited URL is exactly one tier) but do **not** partition answers — one answer can contain citations of two or three tiers. - **Deprecated usage:** some older code/docs use "external" to mean *non-owned* (tracked + secondary combined, e.g. `secondary_cited_run_count`). That is wrong going forward. **External == `secondary` only.** ### The two denominators (`D` and `S`) — never mix them Every citation metric divides by one of exactly two denominators. Which one you pick *is* the difference between the metric families, so name it before you write the math: ``` D = count of prompt-run ANSWERS with ≥ 1 citation (any tier) → Rate, Coverage S = count of citation INSTANCES (every cited URL, all tiers) → Share ``` `D` is answer-grain: an answer citing five of your pages contributes **1**. `S` is instance-grain: that same answer contributes **5**. A metric built on `D` and a metric built on `S` are never comparable and must never be averaged, summed, or charted on a shared axis without labels. ### Family 1 — Citation Rate (answer grain, per tier) All three rates share the denominator `D`: ``` primary_citation_rate = (answers with ≥1 primary citation) / D external_citation_rate = (answers with ≥1 external citation) / D tracked_citation_rate = (answers with ≥1 tracked citation) / D ``` Rules that keep these consistent everywhere: 1. **Denominator is answers-with-any-citation (`D`)** — NOT all runs, NOT answered (non-empty) runs, NOT websearch-capable runs, NOT total citation count. 2. **Numerator is distinct answers**, counted with "has at least one" (`≥1`) semantics — NOT a count of citation instances/URLs, and NOT a sum of per-webpage counts (which double-counts an answer that cited two pages of the same tier). 3. **The three rates are independent, not a partition.** An answer with both a primary and an external citation counts toward both numerators, so `primary + external + tracked` can exceed 100%. This is expected and correct. 4. When `D = 0`, every rate is `0` (or null / "—" in the UI) — never divide-by-zero. ### Family 2 — Citation Coverage (answer grain, per specific source) **Citation Coverage** answers a different question than a citation *rate*: for a **specific** source, domain, or published article, *of the answers that cited anything, how often was THIS item the thing cited?* ``` coverage(source) = (distinct answers that cited this source) / D ``` - Shares the denominator `D` with the tier rates (answers with ≥1 citation of any tier), so coverage and the tier rates read on one consistent base. - Numerator is **distinct answers** (a source cited 3× in one answer counts once), so coverage is always ≤ 100%. It is **not** `times_cited / runs` — that is citation *instances per run*, an intensity that routinely exceeds 100% and must never carry a `%`. - Coverage is Rate's per-source sibling: same denominator, narrower numerator. A tier rate is *not* the sum of its sources' coverages (two sources cited in one answer double-count). ### Family 3 — Citation Share (instance grain, volume) **Citation Share** answers a *volume* question: of all the citation instances we saw, what fraction went to this tier (or this source)? Rate and Coverage count **distinct answers**; Share counts **individual cited URLs**. ``` primary_citation_share = primary_cited_total / S tracked_citation_share = tracked_cited_total / S external_citation_share = external_cited_total / S share(source) = (citation instances for this source) / S ``` Rules: 1. **Denominator is `S`, the instance total** — never `D`, never a run count. Share and Rate do not share a base, and a "share" computed over `D` is neither metric. 2. **Numerator counts instances, not answers.** One answer citing three of your pages contributes **3** to the primary share numerator (it contributes **1** to the primary rate numerator). This is the whole difference between the families. 3. **The three tier shares partition citations and sum to exactly 100%** — each cited URL is exactly one tier. This is the sharpest contrast with the three rates, which are independent and can sum past 100%. **If your tier shares don't total 100%, that is a bug**: a citation was double-classified, dropped, or the numerators and denominator were computed over different scopes/windows. (Per-tier percentages rounded independently may display as 99–101%; round-then-reconcile if it matters.) 4. **Per-source shares over one scope also sum to 100%**, for the same reason. A per-source share and a per-tier share are the same metric at different grains. 5. When `S = 0`, every share is `0` (or null / "—") — never divide-by-zero. **Rate and Share routinely disagree, and that disagreement is the insight.** An answer citing your site once alongside nine third-party URLs contributes a full **1/1 = 100%** to your primary *rate* (the answer did cite you) but only **1/10 = 10%** to your primary *share*. High rate + low share means "you get cited, but you're outnumbered inside every answer." Never substitute one for the other, and never put both on one chart without saying which is which. ### Anti-patterns (these are NOT the citation rate) - `owned_cited_run_count / run_count` — denominator is all runs. ✗ This is "share of all answers that cite you" (call it *owned citation coverage* if you need it), a different metric. - `primary_citations / total_citations` — ratio of citation *instances*. ✗ Not a rate — but not wrong either: this is exactly **Citation Share**. Keep the math, fix the name. - `times_cited / total_prompt_runs` — per-source coverage over all runs. ✗ - Summing per-webpage `cited_run_count` where `source_type = 'tracked'` — double-counts answers that cited multiple tracked pages. ✗ - `_cited_run_count / cited_total` or `_cited_total / cited_run_count` — mixing an answer-grain numerator with an instance-grain denominator (or vice versa). ✗ Meaningless, and can exceed 100% for no interpretable reason. Numerator and denominator must come from the same grain. ### Data requirements **Answer grain** — the **distinct-answer** counts behind Rate and Coverage, per answer or aggregated per group: | Count | Meaning | Role | |----------------------------|-------------------------------------------|--------------| | `cited_run_count` | answers with ≥1 citation of any tier | denominator `D` | | `primary_cited_run_count` | answers with ≥1 primary citation | numerator (primary rate) | | `tracked_cited_run_count` | answers with ≥1 tracked citation | numerator (tracked rate) | | `external_cited_run_count` | answers with ≥1 external (`secondary`) citation | numerator (external rate) | Each rate is `_cited_run_count / cited_run_count`; each coverage is that source's distinct cited answers ÷ `cited_run_count`. **Instance grain** — the **citation-instance** totals behind Share: | Count | Meaning | Role | |------------------------|------------------------------------------------|--------------| | `cited_total` | citation instances, **all tiers** | denominator `S` | | `primary_cited_total` | primary citation instances | numerator (primary share) | | `tracked_cited_total` | tracked citation instances | numerator (tracked share) | | `external_cited_total` | external (`secondary`) citation instances | numerator (external share) | Each share is `_cited_total / cited_total`. Because the tiers partition citations, `primary_cited_total + tracked_cited_total + external_cited_total = cited_total` must hold — treat a violation as a producer bug, not a rounding artifact. > **`cited_total` history hazard.** `cited_total` originally meant *owned-only* > instances and was repurposed to the all-tier total when the per-tier columns landed. > Any window spanning that change mixes both meanings, so a Share computed across it is > silently wrong. Confirm the rows in your window were written by the current producer > (or rebuilt) before trusting `S`. ### Vocabulary (use these names everywhere — never mix them) | Term | Question it answers | Formula | Grain | Range | |------|---------------------|---------|-------|-------| | **Citation Rate** (Primary/External/Tracked) | of cited answers, how many cited this **tier**? | `_cited_run_count / D` | answers | ≤100% per tier; tiers may sum >100% | | **Citation Coverage** | of cited answers, how many cited this **specific source/domain**? | `source_cited_run_count / D` | answers | ≤100% | | **Citation Share** (per tier or per source) | of all citation **instances**, what fraction is this tier/source? | `_cited_total / S` | instances | ≤100%; tiers sum to exactly 100% | | **Citations / run** (frequency) | how many times is a source cited per run? | `times_cited / runs` | instances ÷ runs | 0–∞, **never** `%` | Guardrails: never attach a `%` to a frequency; never call a coverage or a share a "rate" (reserve "Citation Rate" for the answer-tier metric); never call a rate a "share"; Primary/Owned, External/Secondary, Tracked always mean the tier taxonomy above.