Metrics & units

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

{
  "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

value is not the same unit across metric types. This is the single most common integration bug.

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.

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.

Get started

Guides

Metrics & units

The metric envelope

The units trap

Metrics on list endpoints

Search volume

Citation metrics

​The metric envelope

​The units trap

​Metrics on list endpoints

​Search volume

​Citation metrics

The metric envelope

The units trap

Metrics on list endpoints

Search volume

Citation metrics