Score history and ranked reads

Every time a slot writes an entity's state — realtime scoring or a batch refresh — Tessera can also append that write to an append-only score history. The current state stays one row per entity (the state reads surface is unchanged); the history sits beside it and is never mutated.

Endpoint	Returns
GET /slots/{slot}/entities/{type}/{id}/history	one entity's score trajectory, newest first
GET /slots/{slot}/entities:top?by=score|signal|delta	the slot's entities ranked by a score, the surprise signal, or a score change over a window
GET /slots/{slot}/monitors/realized-quality	weekly realized AUC and lift@k of the slot's binary labels

All three need a key with the read scope. Another project's slot or entity is indistinguishable from a missing one (404 not_found).

What a history row holds

{
  "computed_at": "2026-07-01T09:00:02Z",
  "as_of": "2026-07-01T09:00:02Z",
  "scores": { "churned_30d": 0.83 },
  "signals": { "behavior_surprise": 0.12, "propensities": { "order.completed": 0.31 } },
  "segment_id": "sgm_01j8…",
  "bundle_id": "bnd_01j…",
  "model_fingerprint": "9f3c…",
  "event_cursor": { "timestamp": "2026-07-01T08:12:33Z", "event_id": "evt-1041" },
  "reason": "event"
}

computed_at is when the state was written; event_cursor is the last event it incorporated, so every point carries its provenance. signals, segment_id and reason are omitted when the write had none (batch refreshes carry no reason). History never stores embeddings.

Plans, sampling and retention

History is a plan feature, configured as data in the plan catalog (limits.state_history):

• enabled — plans without history record nothing and meter nothing;
• min_write_interval_seconds — a write is recorded only when the entity's newest retained row is at least this old (so a hot entity keeps at most one point per interval);
• retention_days — older rows are deleted by a daily sweep;
• downsample_after_days — beyond this age the sweep keeps exactly the newest row per entity per UTC day.

Recording is asynchronous and can never slow down or fail scoring: under backpressure points are dropped (and counted) rather than delaying state writes. Appended rows are metered for your plan (internally, as state_history_rows); the v1 GET /v1/usage response does not report that metric.

Reading a trajectory

curl -s "$TESSERA_API_BASE/slots/media-prod/entities/viewer/v-1041/history?limit=50" \
  -H "authorization: Bearer $TESSERA_API_KEY"

Pages are newest first with the usual limit (≤ 200) / cursor pagination; from (inclusive) and to (exclusive) bound computed_at within your plan's retained window. Add threshold=0.8 to get deviation_started_at: the start of the entity's current run of values at or above the threshold (the surprise signal by default, or a score with label=), or null when the latest value is below it.

Ranked reads

curl -s "$TESSERA_API_BASE/slots/ops/entities:top?by=delta&label=delayed_next_leg&window=7d&limit=50" \
  -H "authorization: Bearer $TESSERA_API_KEY"

• by=score ranks the current scores[label] (class= for a multiclass label); by=signal ranks behavior_surprise; by=delta ranks the change of scores[label] since now − window (default 7d, at most your plan's retention).
• Order is value descending, ties broken by entity id; entities without the ranked value never appear, and rows scored by a model other than the slot's active one are excluded and reported as stale_rows_excluded.
• Rankings are computed from a full scan of the slot (up to 1,000,000 state rows) and persisted as a snapshot of the top 1,000. A request without a cursor reuses a snapshot younger than max_age_seconds (default 60, max 3600); the cursor pins its snapshot, so paging never reorders even while scores keep changing.
• An entity you erase (POST /entities/{type}/{id}:delete) is removed from every stored snapshot with the rest of its data and is never returned again, not even from a snapshot built before the request or through a cursor you already hold; the entries after it keep their ranks (the sequence has a gap, and paging neither repeats nor skips another entity). Its score history is erased too.

Realized quality

A daily job joins each matured label observation to the score the entity had at the label's anchor time (observed_at − maturation_days) — a score computed later can never be used — and reports per ISO week the realized AUC and realized lift@k with 95% bootstrap intervals. Weeks with fewer than 50 joined observations report insufficient_support; non-binary labels report unsupported_task.