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

# Quality metrics: read and compose your own report

> Read per-clip counts and seconds from the Quality Indexing API and compose your own report by totalling any subset of clips you care about.

The Quality Indexing endpoints publish what was measured about your footage.
They do not publish a verdict about it — you compose that yourself, from numbers
you can re-total however you like.

Every field's type is in the API reference and its meaning is in the
[Metric glossary](/glossary); this page is about how the pieces fit together
and why they are shaped the way they are.

## Counts and seconds are the source of truth

A share commits you to a denominator we picked. Every per-clip figure is
therefore a count of frames or a number of seconds, so any subset of clips you
care about — one operator, one site, one week of collection — can be totalled
without asking us to compute it.

The corpus-level endpoints do publish shares, because at corpus level the
denominator is unambiguous, and each one arrives beside the population it was
computed over: how many clips were assessed, how much footage could not be, and
how many clips were never decoded. A number without its denominator is not
worth much, so they always travel together.

## An absent field is not a zero

A clip that carries no `frame_quality` object was never decoded. A clip whose
`frame_quality.active` is `0` was decoded and found to contain no usable frames.
Those are opposite facts, and averaging the first as if it were the second
silently drags your numbers down. Nothing is filled in with zeros to make the
rows uniform — check for the field's presence before you aggregate it.

Which fields this applies to, and what absence means for each, is in the
[Metric glossary](/glossary). The [Quickstart](/quickstart) walks the endpoints
in the order you would call them.

## Descriptive and directional metrics

Vocabulary diversity is descriptive. More environments, objects, or actions
are not automatically better: a buyer should compare the returned terms, tiers,
and coverage with the kind of footage they need. The same corpus therefore has
one query-independent vocabulary, while different buyers can make different
decisions from it.

Cleanliness is directional: a larger usable share generally indicates more
legible footage. `jerky` is the exception inside it, because it cannot separate
camera shake from fast subject motion — see the
[glossary](/glossary#cleanliness) before you treat it as a defect.

## Reconciling the counts

Everything a section reports describes the same set of terms, so these hold and
are worth asserting in your own pipeline:

* The term table is exactly the published terms. Every one of them is either
  counted in `distinct_terms` or listed in `untiered_terms`.
* No clip row names a term absent from the table.
* `rarefied_distinct_terms` is the only count comparable against a *different*
  corpus, and `comparable_depth_clips` states the depth it was taken at. Setting
  two raw counts side by side compares sampling effort as much as content; the
  [glossary](/glossary#counting-a-vocabulary) says why.

## Access

Every endpoint here requires a credential and returns only datasets your
organization is entitled to read. See [Authentication](/authentication).