List Metrics Reference

A list metric returns a ranked table: a set of declared column headers, a default sort, and limit / offset / order pagination on top. Twenty-two exist. They are the “top ten of something” half of the analytics catalog — top referrers, top entry pages, sessions by country, seconds of a video that get rewatched. The other half returns a single number with a trend, and those are defined in the metrics reference.

Not all twenty-two are rendered anywhere in the CMS. Seven are reachable only through the API, the assistant and MCP, and the table below says which — so you do not go hunting for a screen that was never built.

The master table

Every row is a real registry entry. The Columns column gives the declared headers in the order the API returns them; Rendered in names the surface that draws it today.

The minimum-tier column for every feature in the product is owned by feature availability by plan. A 402 from a gated metric follows the standard upgrade contract described in when a feature is gated.

Traffic and navigation

Seven metrics answer “where did this traffic come from, and where did it go”.

inboundAttributionMetric is the one that answers which channel sent this traffic; how it is assembled, and why a click that happened on one of your own pages is dropped from the site-wide view, is in journeys, funnels and attribution.

The two referrer metrics, and their swapped-sounding names

Leed has two referrer metrics, and their display names read backwards from what you would guess.

The one named “Top Referrers” is the more granular one, and it is the one nothing renders. Both cards you can actually see on screen — the Top referrers card on the Know dashboard and the Top Referrers block in the editor’s Page Analytics panel — are backed by referrerHostMetric, whose catalog name is “Referrers”.

Practically: if you are reading a screen, you are looking at hosts. If you want individual referring URLs, query referrersMetric yourself.

A null referrer host renders as (direct) on the Know card — someone who typed the address, followed a bookmark, or arrived from a client that strips the referrer.

Top Destination and Top Inbound are page-scoped by nature

topDestinationPagesMetric and topInboundPagesMetric both require a pageId; the query throws without one. That is not a limitation, it is the question they ask. “Where did readers go next” and “which of my pages sent readers here” are only meaningful about a specific page, which is why both appear in the Page Analytics panel and nowhere on the site-wide dashboard.

Three more metrics carry the same requirement for the same reason: timerMetric, pageViewDetailsMetric and internalClickMetric are all per-page. The six per-asset media metrics require an assetId instead.

Audience

browsersUsedMetric declares exactly two columns, Operating System and Count, even though the block that renders it in the editor is headed Browsers & Devices. The heading promises more than the metric returns. Nothing is broken; the columns are the contract.

Both geography metrics count sessions, and approximate location comes from network-level request data rather than any geolocation permission prompt — a visitor is never asked.

Engagement

timerMetric always returns the same two rows for a page, because the active-time tracker only ever emits two event names. active tells you the average uninterrupted reading stretch; away tells you how long people idle before coming back. “Avg / User” is how many times each state occurred per visitor, so a high away occurrence count means readers keep leaving and returning to the tab.

pageViewDetailsMetric is your scroll-depth measure. It counts visibility events per element, filtered to percent > 0, so an element that never entered the viewport at all contributes nothing rather than a zero row. Elements are identified by the data-id the site build stamps on tracked blocks.

internalClickMetric is the tabular twin of the click-count overlay, and both need the same plan. The overlay draws the same numbers as badges over a live preview of the page; the metric hands you the raw table.

Two metrics with no screen

pageViewDetailsMetric and internalClickMetric are rendered by no CMS screen at all. There is no panel, no card, no tab. They exist for the API, the assistant and MCP.

If you want per-element view or click counts as data, ask the assistant for them or call GET /api/analytics directly. If you want them as a picture, the overlay is the picture — but only for pages that live in your site repository.

Media

Two of the eight summarize every asset; six describe one asset second by second.

The Most Listened Audio summary has no dashboard card. Audio is visible on the audio asset’s own page and through the API; there is no audio equivalent of the Know Most viewed videos widget.

The eight media metrics are explained in full, with what a retention curve actually shows and how to read a drop-off, in media engagement analytics.

How to read “Total Time Viewed”

Total Time Viewed is deduplicated. A viewer who rewatches the same thirty seconds three times contributes thirty seconds, not ninety. The column reports unique seconds of the asset that a viewer was present for.

This is a deliberate product decision, not an accident of the query: a raw total-seconds column existed and was removed because it was actively misleading — a single obsessive rewatcher could out-total a hundred genuine viewers. There is no raw figure anywhere in the product to reconcile this against, so do not try.

Average Time Per User divides the deduplicated total by unique viewers, so it answers “how much of this did a typical viewer actually see” rather than “how long was it playing”.

The same column appears on the video and audio asset pages and on the Know Most viewed videos card, and it is deduplicated in all three; what “Total Time Viewed” counts works through an example.

Querying a list metric

Every list metric is served by GET /api/analytics, the same endpoint the counted metrics use. Pass the query key as metric, plus start and end.

curl -G "https://app.leed.ai/api/analytics" \
  --data-urlencode "metric=referrerHostMetric" \
  --data-urlencode "start=2026-08-01T00:00:00.000Z" \
  --data-urlencode "end=2026-08-31T23:59:59.999Z" \
  --data-urlencode "limit=10" \
  --data-urlencode "offset=0" \
  -H "Authorization: Bearer $LEED_TOKEN"

The response carries the declared headers alongside the rows, so a client can render the table without knowing the metric:

{
  "name": "Referrers",
  "headers": [
    { "name": "Referrers", "value": "referrerHost", "type": "faviconUrl" },
    { "name": "Views", "value": "frequency" }
  ],
  "values": [
    { "referrerHost": "news.ycombinator.com", "frequency": 412 },
    { "referrerHost": "www.google.com", "frequency": 288 }
  ],
  "count": 37
}

count is the total number of rows available, not the number returned, so it is what you page against.

Sorting is two parameters, not one: order names the column and desc picks the direction, defaulting to descending whenever order is present. The column must be one of the value keys in that metric’s own headers — anything else is rejected with an error naming the columns that are available. Omit order entirely and you get the metric’s default sort from the table above.

The same window rules apply as everywhere else in analytics: a single request may span at most 365 days (400 “Range cannot exceed 365 days”), end must be after start (400 “end must be after start”), and a range reaching past your plan’s retention is either silently clamped or refused with a 402. All three are set out in date ranges and retention.

An unrecognized metric value is 400 Unknown metric: X, so a typo fails loudly rather than returning an empty table.

Six results that are not catalog metrics

A handful of analytics results in Leed are not registry metrics at all — they have their own response shapes and their own endpoints. They are listed here so that a name you saw somewhere is findable.

elementClicks is the odd one out even here: it is neither a counted nor a ranked metric, it is accepted by GET /api/analytics as a metric value anyway, and it requires a pageId (400 pageId is required for elementClicks without one). It carries the same Growth gate as internalClickMetric.