# Metric Definitions

https://api-docs.lumar.io/docs/ai-visibility/ai-visibility-metrics

AI Visibility reports several metrics that answer different questions. This page defines each one, the field that returns it, and how it is calculated.

## At a glance

| Metric                  | Field                  | Range    | Answers                                                 |
| ----------------------- | ---------------------- | -------- | ------------------------------------------------------- |
| Presence Rate           | `avgPresenceRate`      | 0–100    | How often does the brand appear in AI answers?          |
| Quality Score           | `avgQualityScore`      | 0–100    | When the brand appears, how well is it presented?       |
| Visibility Index        | `avgVisibilityIndex`   | 0–100    | Which brands rank highest overall?                      |
| Mention Share of Voice  | `mentionShareOfVoice`  | 0–100    | What share of all brand mentions does this brand hold?  |
| Citation Share of Voice | `citationShareOfVoice` | 0–100    | What share of all brand citations does this brand hold? |
| Average position        | `avgBrandPosition`     | 1 and up | Where in the answer does the brand's citation appear?   |
| Average sentiment       | `avgBrandSentiment`    | —        | How positively do answers talk about the brand?         |

**Absolute versus relative.** Presence Rate, Quality Score and Visibility Index describe one brand on its own: every brand in a project can have a 100% Presence Rate at the same time. Share of Voice is relative: shares are split between the brands in scope and sum to 100%, so one brand gaining share means others losing it.

All metrics respect the query's scope filters — `dateRange`, topic, prompt, `aiProviderTypes` and `country`.

## Presence Rate

The percentage of finished prompt runs in which the brand was mentioned **or** cited.

```
presence_rate = runs where the brand was mentioned or cited / total finished runs × 100
```

A run where the brand is both mentioned and cited counts once. Use Presence Rate to track reach: whether AI providers bring the brand up at all.

## Quality Score

How favourably the brand is presented when it does appear, independent of how often it appears.

```
quality_score = 0.75 × avg_brand_mention_quality + 0.25 × avg_citation_quality
```

- `avgBrandMentionQualityScore` (0–100) — average quality of the brand's mentions: how prominently and favourably the answer names it.
- `avgCitationQualityScore` (0–100) — average quality of the citations to the brand's domains.

A missing component counts as 0, so a brand that is mentioned but never cited scores at most 75. A brand that appeared in one run with excellent coverage can have a high Quality Score and a low Presence Rate.

## Visibility Index

A single ranking number that combines quality with how often the brand appears. Use it to order brands. Use Presence Rate and Quality Score to explain the ranking.

```
visibility_index = avg_citation_quality × √(citation_runs / total_runs) × 0.25
                 + avg_brand_mention_quality × √(mention_runs / total_runs) × 0.75
```

The square root softens the appearance penalty: appearing in 10% of runs scales quality by 31.6%, not 10%. Consistent brands still outrank rare ones:

| Brand | Appears in    | Quality | Presence Rate | Visibility Index |
| ----- | ------------- | ------- | ------------- | ---------------- |
| A     | 10 of 10 runs | 80      | 100           | 80               |
| B     | 1 of 10 runs  | 100     | 10            | 31.6             |

`avgVisibilityScore` is the former name of this metric. It returns the same value and is deprecated in favour of `avgVisibilityIndex`. On a single prompt run, `visibilityScore` is likewise a deprecated alias of `qualityScore`.

## Share of Voice

The brand's share of all brand appearances in AI answers within the current scope.

```
mention_share_of_voice  = answers mentioning the brand / Σ answers mentioning each brand in scope × 100
citation_share_of_voice = answers citing the brand     / Σ answers citing each brand in scope × 100
```

- **One appearance per answer.** A brand named five times in one answer counts once. Repeated instances stay visible in `totalBrandMentions` and `totalBrandCitations`. The Share of Voice numerators are `mentionAnswerAppearances` and `citationAnswerAppearances`.
- **The denominator is every brand in scope.** That means every brand mentioned or cited under the current filters, not a fixed competitor list. Filtering to one topic gives each brand's share within that topic.
- **`Context` brands are excluded.** Platforms and surfaces that answers name constantly, such as Google or ChatGPT, keep their appearance counts but are left out of every denominator. You choose which brands are `Context`; see [Brands](./ai-visibility-brands.md).
- **`brandTypes` narrows the comparison set.** Passing `[Own, Competitor]` rescales shares so they sum to 100% across your brand and its competitors only. Brands outside the set return `null` (or `0` on non-null fields) for their share. `getAiVisibilityTopBrands`, `getAiVisibilityTopics` and `getAiVisibilityShareOfVoiceTrend` take this as `brandTypes`; `getAiVisibilityBrands` takes it as `types`.
- **Unattributed citations are excluded** from both sides of the ratio.
- **Not position-weighted.** A brand named last counts the same as one named first; use position or the Visibility Index for prominence.

Shares are rounded to 2 decimal places, so they may not sum to exactly 100.

### Reading the denominator

The denominator changes as new brands are discovered. Tracking more prompts, or a new competitor entering answers, can lower every brand's share without any change in its own performance. Results that return Share of Voice also return the denominator so you can tell the difference: `totalMentionAnswerAppearances`, `totalCitationAnswerAppearances` and `brandsInScope`. Brand lists also return `others`, which combines every in-scope brand not on the current page, so returned rows plus `others` add up to the whole.

When you compare with an earlier period, pass the same `brandTypes` (or `types`) to both windows. Shares calculated over different sets of brands are not comparable.

## Position and sentiment

| Field               | Meaning                                                                                                                          |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `avgBrandPosition`  | Average position of the brand's citations within answers. `1` is the first citation; lower is better.                            |
| `bestBrandPosition` | The brand's best (lowest) citation position.                                                                                     |
| `avgBrandSentiment` | Average sentiment of the brand's mentions. Each mention's `sentiment` includes a `sentimentJustification` explaining the rating. |

## Counts

| Field                       | Counts                                                       |
| --------------------------- | ------------------------------------------------------------ |
| `totalBrandMentions`        | Every mention instance, including repeats within one answer  |
| `totalBrandCitations`       | Every citation instance, including repeats within one answer |
| `mentionAnswerAppearances`  | Distinct answers that mention the brand                      |
| `citationAnswerAppearances` | Distinct answers that cite one of the brand's domains        |

## Which metric to use

| Question                                                                       | Use                                                                |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| Are AI providers bringing up our brand at all?                                 | Presence Rate                                                      |
| When they do, is the coverage good?                                            | Quality Score, then sentiment and position                         |
| Who leads the category overall?                                                | Visibility Index                                                   |
| How much of the conversation do we own compared with competitors?              | Share of Voice with `brandTypes: [Own, Competitor]`                |
| Did our share fall because we lost ground or because more brands were tracked? | Share of Voice alongside `brandsInScope` and the appearance totals |

## Empty data

- `getAiVisibilityBrands` metrics need a `dateRange`. Without one, Presence Rate, Quality Score and Visibility Index return `0`, and the component, position and sentiment fields return `null`. `getAiVisibilityTopBrands` defaults to the last 30 days when `dateRange` is omitted.
- In time series, a bucket with finished runs but no appearance for the brand returns `0`. A bucket with no finished runs returns no data point. Build the bucket grid from `dateRange` and `timeBucket` to show those gaps.

## Related

- [Visibility Scores](./ai-visibility-scores.md) — time-series queries for these metrics
- [Brands](./ai-visibility-brands.md) — brand lists, types and Share of Voice rankings
- [Topics](./ai-visibility-topics.md) — per-topic metrics, leaders and gaps