> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognizo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Metrics & units

> What visibility, share of voice and sentiment actually measure — and the units traps.

Cognizo's metrics all come out of the same machinery: every tracked prompt is
run against AI providers on a schedule, each answer is parsed for brand
mentions, and the metrics are aggregations over those **runs**.

Three endpoints return the canonical metric envelope — `visibility`,
`share_of_voice` and `sentiment` — at both brand and prompt/region level. They
share one response shape.

## The metric envelope

```json theme={null}
{
  "data": {
    "metric_type": "visibility",
    "date_range": ["2026-07-06T00:00:00Z", "2026-08-05T23:59:59Z"],
    "aggregate_metrics": {
      "start_date": "2026-07-06",
      "end_date": "2026-08-05",
      "values": [
        { "brand_name": "Acme", "found_brand_id": "…", "value": 42.1,
          "diff": 3.4, "rank": 1, "is_target": true },
        { "brand_name": "Globex", "found_brand_id": "…", "value": 30.8,
          "diff": -1.2, "rank": 2, "is_target": false }
      ]
    },
    "time_based_metrics": [
      { "start_date": "2026-07-06", "end_date": "2026-07-12", "values": [ ] }
    ]
  }
}
```

| Field                | Meaning                                                                                                                      |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `metric_type`        | `visibility`, `share_of_voice`, `sentiment`, or the position metrics `first_position` / `middle_position` / `last_position`. |
| `aggregate_metrics`  | One row per brand for the **whole window**.                                                                                  |
| `time_based_metrics` | The same rows per bucket — bucket size comes from `filter[granularity]` (`day` by default).                                  |
| `value`              | The number. **Its unit depends on `metric_type`** — see below.                                                               |
| `diff`               | Change vs the **previous equal-length period**, in the same unit. `null` when no prior value can be computed.                |
| `rank`               | 1-based rank by `value` within the metric (1 = highest). Present on aggregate rows, `null` when unranked.                    |
| `is_target`          | `true` for your own brand, `false` for competitors.                                                                          |
| `found_brand_id`     | Canonical brand-mapping id; `null` when the brand wasn't resolved to a mapping.                                              |

## The units trap

<Warning>
  `value` is **not** the same unit across metric types. This is the single most
  common integration bug.
</Warning>

| Metric                                                 | Unit                                                               | Null?                                                  |
| ------------------------------------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------ |
| `visibility`                                           | 0–100 **percentage** of the brand's runs where it appeared         | Never — `0` when there's no data                       |
| `share_of_voice`                                       | 0–100 **percentage** of all brand mentions that were this brand    | Never — `0` when there's no data                       |
| `first_position` / `middle_position` / `last_position` | 0–100 **percentage** of runs where the brand appeared in that slot | Never — `0` when there's no data                       |
| `sentiment`                                            | **Average score on a 1–100 scale** — not a percentage              | `null` when the brand has no scored runs in the window |

Two consequences worth internalising:

* **Don't re-aggregate `sentiment` client-side.** It's already an average, not
  a count. Averaging the daily averages is not the window average — read
  `aggregate_metrics` for that.
* **`0` and `null` mean different things.** For visibility and share of voice,
  `0` means "we ran the prompts and the brand never showed up". For sentiment,
  `null` means "nothing was scored", which is not the same as neutral.

## Metrics on list endpoints

List endpoints embed the same numbers as flat fields — same units, same
`_diff` convention against the previous equal-length period:

* **Prompts** (`list_brand_prompts`): `visibility`, `visibility_diff`,
  `sentiment`, `sentiment_diff`, `citation_share`, `citation_share_diff`,
  `mentioned`, `top_competitors`, `last_run`, plus search-volume fields.
* **Topics** (`list_brand_topics`): `visibility`, `share_of_voice`,
  `sentiment`, `citation_share` and their diffs, plus `prompt_count` and
  `top_brands`.
* **Brands** (`list_brands`): `visibility` is the 30-day figure, `null` on
  brands where it hasn't been computed.

### Search volume

Prompt rows carry both a raw `volume` and a bucketed `volume_range`
(`<10`, `10-50`, … `1m+`). The bucket is derived from the raw number — use
`volume_range` for display and grouping, `volume` for sorting, and expect both
to be `null` for prompts where volume hasn't been estimated yet.

## Citation metrics

Citations are counted per AI answer, so they follow their own vocabulary:

| Metric                   | Meaning                                                     |
| ------------------------ | ----------------------------------------------------------- |
| `total_citation_count`   | All citations of that domain/page in the window.            |
| `brand_citation_count`   | The subset attributed to the target brand.                  |
| `citation_share`         | Your share of the citations in scope, as a percentage.      |
| `mention_share`          | Your share of the brand mentions in scope, as a percentage. |
| `target_brand_mentioned` | Whether your brand appears on that cited page.              |

The `citation_share` and `mention_share` endpoints return a time series where
each point carries `count`, `total`, `share_percent`, plus rolling
`average_count` / `average_percentage`.

<Note>
  Dates on the citation share series come back as `"YYYY-MM-DDT00:00:00"` with
  no timezone offset — they're period starts in the workspace's local time, not
  UTC instants. Parse them as local dates.
</Note>