Compass Admin UI: Reading Your Analytics

Compass reports on what the recommendation API served to your readers and what they did with it. This page explains what each number counts, so that the ones you act on mean what you think they mean.

For the editorial actions in the same app, see Compass Admin UI: Editorial Controls.

Note

Compass analytics is minute-grain, not real-time. Every number is read from a projection that is rebuilt continuously, and the Overview tells you how old the data is. Expect a lag of minutes, and don’t use Compass as a live ticker during a breaking-news event.

The vocabulary, before the dashboard

Four definitions do most of the work. Getting these right is the difference between a number you can act on and one you’ll misread.

Impressions count views of a story, not API calls

An impression in Compass is a recommendation exposure: a reader actually saw the story in a recommendation slot, qualified by the viewport. It is not a count of recommendation API requests, and it is not a count of lists rendered. A request that returns ten stories the reader never scrolls to contributes no impressions.

There are three kinds of clicks, and only one of them is in CTR

This is the single most important distinction in Compass analytics:

Click class	What it is	How to use it
Confirmed clicks	A click that carried valid attribution context and matched an exposure of that same story inside the attribution window.	The CTR numerator. This is the customer-facing click number.
Context-only attributed clicks	A click that carried valid attribution context but never matched an exposure.	Real evidence of recommendation-driven engagement. It does not raise CTR, and it must never be turned into a second CTR.
Unattributed clicks	A click with no usable attribution context.	Evidence that interaction happened — nothing more. Never derive a rate from it (see the caution below).

Caution

Unattributed clicks are deduplicated only per source object, so a single click appearing in two source objects is counted twice. Treat the figure as “interaction occurred”, never as a precise count, and never as the numerator or denominator of a ratio.

Confirmed CTR is a lower bound, not an exact rate

Matching a click to its exposure is one-shot. Event files arrive out of order — that is normal with batched delivery — and if a click is processed before the exposure that produced it, the click is permanently classified as context-only. It is never promoted to confirmed when the exposure lands later.

So confirmed CTR slightly undercounts, and the size of the undercount moves with your delivery patterns. Use it the way it holds up: trend it over time and compare it between windows, where the undercount applies consistently. Don’t treat a single figure as your exact click-through rate, and don’t reconcile it against a rate computed in another analytics tool — the two are counting different things. If you need to see how much is being missed, the context-only series in the advanced view is that gap.

The four headline metrics

Metric	What it counts
Impressions	Times a recommended story was seen by a reader in a recommendation slot.
Clicks	Confirmed clicks — clicks matched to an accepted exposure of that story.
CTR	Clicks ÷ Impressions. Shown as empty rather than 0 % when there were no impressions at all.
Avg. served position	The average rank at which clicked stories were served in the list, weighted by clicks. Positions are shown 1-based, so 1.0 means clicks landed on the first slot. Lower is better.

The Overview

Overview is the default section, scoped to the website selected in the left column. Its chrome controls every section on the page at once:

• A window selector — Last 24 hours, Last 7 days, or Last 30 days.
• Auto refresh — off, or every 1, 3, 5, or 10 minutes; plus a manual Refresh button.
• A Last updated N min ago label, which is how old the underlying projection is — not when you last loaded the page.
• A stale banner — Data may be stale. Last projected {ago} ago. — which appears once the projection is more than five minutes behind.

Content recommendations

Articles served through the recommendation API. Four tiles — Impressions, Clicks, CTR, Avg. served position — plus a chart over the selected window.

Each tile carries a period-over-period arrow comparing the selected window against the immediately preceding window of equal length: with Last 7 days selected, the comparison is the seven days before that. The arrow is absent when the previous window’s value was zero or unavailable, so a missing arrow means “nothing to compare against”, not “no change”.

Pinned content

The story currently pinned to the top of the feed. The pinned story’s own card, with Impressions, Clicks, and CTR.

Note

This section is always captioned Last 24 hours and stays on that window regardless of the window selector at the top of the page.

No analytics for this story yet means the story has no measured activity — normal for a pin that went up minutes ago. Analytics unavailable means the request failed, which is a different problem.

Catch up cards

Modules that help readers catch up on stories they’re following. The tiles are deliberately the same three as the recommendations section — Impressions, Clicks, CTR — so the two sections read the same way, plus a CTR-over-time chart for the selected window.

If the website has no Catch Up telemetry at all you’ll see Catch up cards are not enabled. The SDK only emits Catch Up events when it renders a card, so this state means “no cards have rendered here”, which usually means Catch Up isn’t integrated on this website yet.

See Catch Up analytics below — the labels match the recommendations section, but two of the caveats do not.

The advanced view

The View all metrics button on the Content recommendations section opens Content recommendations — Dive deeper into performance of the recommendations API. Back to Overview returns. This view is where you diagnose the quality of the data feeding recommendations, rather than the performance of the recommendations themselves.

Clicks by type

The three click classes from above, charted:

• Confirmed — clicks matched to a specific recommended story.
• Context only — clicks with attribution context that couldn’t be matched to a served story.
• Attributed (total) — every click carrying attribution context: confirmed plus context-only.

A large context-only share relative to confirmed is the signature of exposure events arriving late or not at all, rather than of readers behaving differently.

Event-stream readiness

Strength of the behavioral data feeding the recommendations API. A score from 0 to 100 with a state badge, the number of events in the window, the attribution rate, and the window itself (Last 24 hours).

The two score descriptions you’ll see are Strong enough to personalize. Recommendations are running on real behavioral signal. at the healthy end, and Signal quality is low. Personalization may be unreliable. at the weak end.

Caution

The readiness score is a directional indicator, not a guarantee of recommendation performance. It tells you whether your event stream looks healthy enough to personalize on; it does not predict CTR. A high score is not a promise of engagement, and a low score on a genuinely low-traffic website can be accurate rather than a defect.

Read it as a diagnostic on your integration, and act on the dimensions rather than the single number — they name what to change. The score carries a version identifier, so if you track it over time, check that alongside the value: a shift in the score without a matching shift in your event volume means the scoring changed, not your data.

Readiness describes your organization’s whole recommender pipeline, not one experience. It has no per-experience filter — Catch Up traffic is excluded from the attribution-completeness dimension but still counts toward total events and user reach.

Readiness dimensions

Seven dimensions, each with a value and a status. The remediation text below is the guidance the UI itself shows:

Dimension	What it measures	Unit	If it’s below target
Volume	Total events received in the rolling window	events	Increase event volume from your integration, or widen the time window.
Attribution completeness	Share of recommendation events carrying usable attribution context	of events	Include attribution context on recommendation events so clicks can be matched.
Diversity	Number of distinct event types seen	event types	Emit a wider range of event types, such as exposures, clicks, and conversions.
Distinct users	Estimated distinct users seen	users	Drive more unique users to recommended content, or widen the window.
Engagement depth	Average events per distinct user	events / user	Encourage repeat interactions per user across a session.
Item concentration	Share of activity captured by the single most active story	in top item	Spread recommendations across more items so activity is less concentrated.
Recency	How recently the latest event arrived	since last event	Check that events are flowing in near real time without delivery lag.

Each dimension — and the overall score — carries one of five states:

State	Meaning
Healthy	Meeting the target.
Warn	Below target, still usable.
Weak	Well below target.
Insufficient data	Not enough events yet to assess.
Not applicable	Not measurable for this window.

Attribution completeness is the dimension to fix first if it’s low: it is what determines whether clicks can be matched to exposures, and therefore whether your CTR is meaningful at all. See Recommendation Attribution for the tagging that populates it.

Readiness over time

The same score as a trend, which is the more useful read: a readiness score sliding down over several days points at an integration that is degrading, and is worth investigating even while the absolute number still looks acceptable.

Item performance

Top recommended items ranked by exposure volume. A table of your stories covering the story, its title, impressions, confirmed clicks, CTR, and average served position.

Two things to know about this table:

• Titles are best-effort. The title is looked up at read time and shows as (no title) for a story that has since been deleted or is otherwise missing from the catalog. The metrics for that row are still valid.
• It is a truncated ranking, not a paginated list. There is no next page. If the view reports that results were truncated, the ranked list was longer than the row limit — narrow the time window or the surface filter to see further down.

A Show raw data affordance exposes the underlying response for the view.

Catch Up analytics: read these differently

Catch Up has no dedicated analytics endpoint. Its numbers come from the same recommendation analytics endpoints, filtered to the Catch Up experience — which is exactly why the Overview labels match. Three caveats change how they read.

Impressions are per segment, not per card

Catch Up counts two different things, and the difference is roughly a factor of four:

Concept	Grain
Cards shown	One per rendered Catch Up card.
Impressions	One per material segment within a card — roughly three to five per card.

The Overview shows Impressions. There is no “Cards shown” tile. So Catch Up impressions are not a count of cards that appeared in front of readers, and reading them that way overstates card volume several times over. Catch Up CTR uses impressions as its denominator, which is a deliberate choice: it keeps Catch Up CTR comparable to the Content Recommendations CTR sitting next to it on the same page.

Not every rendered card is measured

Catch Up telemetry is emitted only for storyline-driven cards. Cold-start cards built from popular content are rendered to readers but not measured, and quiet segments are likewise unmeasured. On a website that is still accumulating reader signal, readers may be seeing meaningfully more Catch Up content than the numbers show.

Per-story Catch Up history is short

Catch Up reports per-story impressions and confirmed clicks, but the per-story view reaches back only about 25 hours. Questions of the form “how did this story perform in Catch Up last week?” have no answer here — if you need that history, capture the per-story figures on a daily schedule and retain them yourself.

The aggregate Catch Up tiles and CTR chart are unaffected and cover the full window selector.

Empty, insufficient, or broken?

These three look similar on a dashboard and mean very different things.

What you see	What it means	What to do
Zeros across the window, CTR empty	Empty window. The query succeeded and there was genuinely no activity — no exposures means no CTR to compute.	Widen the window, or check that the integration is emitting events on this website.
A readiness score of 0 with Insufficient data states	Not empty. Events exist, but the rolling count is under the floor needed to assess quality.	Nothing is broken. Get more traffic through recommended content, or widen the window.
No readiness reading at all	Nothing has been projected yet for this organization.	Expected before the first events land. If events are flowing, treat it as an integration problem.
An error message	The request failed.	This is not zero traffic. Retry; if it persists, raise it — don’t record the period as having no activity.

Caution

The distinction that matters most: no freshness information means no underlying data, not fresh data. An absent projection timestamp is the “nothing here yet” state, not the “up to the minute” state.

The Catch Up section’s live indicator follows the same logic — it is derived from whether a projection exists and whether any cards were served in the window, not reported directly. “No activity in window” and “nothing projected yet” are different states with different causes.

The endpoints behind the numbers

Everything above is served by four read-only endpoints, which you can also query directly:

Endpoint	Powers
GET /analytics/v1/ctr	Impressions, clicks, CTR, average served position, and the clicks-by-type chart
GET /analytics/v1/engagement	Card-level Catch Up counters
GET /analytics/v1/items	Item performance and the pinned story’s own metrics
GET /analytics/v1/readiness	The readiness score, dimensions, and trend

All four are scoped to your organization from the gateway credentials on the request. A caller never supplies an organization or tenant identifier.

The three time-series endpoints share a query shape: a required window_start (inclusive) and window_end (exclusive) in UTC, an optional granularity of minute, hour, or day (hour by default), and optional site_id and surface_id filters. /items takes a limit instead of a granularity. /readiness takes only an optional window and defaults to the last 24 hours.

Caution

The experience parameter — recommendations, catch_up, or all — defaults to recommendations. Omit it when you meant to query Catch Up and you will get recommendation numbers back with no error and no warning. /readiness has no experience filter by design; a value passed there is ignored.

Two limits to design around: a response is capped at 1,500 time buckets and a query window at 92 days, and exceeding either is an error rather than a truncated result. Requested windows are snapped to bucket boundaries, and the response echoes the window it actually used — read that back rather than assuming your requested window was honored exactly.