Posterior

Every model figure Levered shows (traffic share and probability of best, expected rewards, lifts, progress, importance, per-segment figures) is computed from the optimization's posterior when it is read. The other endpoints return counts and configuration only. To read a model figure, query the posterior with SQL.

This applies to optimizations whose model_source is store, which is every new one. Optimizations created before the posterior store have model_source: "bandit" and keep their figures on the results endpoints, as before; see Optimizations.

Query the posterior

POST /api/v2/posterior/optimizations/:optimizationId/query

Auth: Required. A Clerk bearer token or an API key (Authorization: Bearer <key> or X-API-Key: <key>).

Runs one read-only SQL query (DuckDB dialect) over the optimization's posterior draws and the views described below. Each published posterior is a version, named after the time its fit finished; every fit publishes a new one.

Request body:

{
  "sql": "SELECT variant_key, share FROM thompson_traffic_share ORDER BY share DESC",
  "params": {},
  "model_version": "latest"
}

Response:

{
  "columns": ["variant_key", "share"],
  "rows": [
    ["{\"cta_text\":\"lv_cta_text_1\",\"headline\":\"lv_headline_0\"}", 0.62],
    ["{\"cta_text\":\"lv_cta_text_0\",\"headline\":\"lv_headline_0\"}", 0.21]
  ],
  "model_version": "2026-10-26T10-15-00Z",
  "available_versions": ["2026-10-26T10-15-00Z", "2026-10-25T10-12-00Z"],
  "n_samples": 2000,
  "elapsed_ms": 140,
  "warnings": []
}

Errors carry { "error": "<message>" }:

Until the first posterior is published, the policy is an even split over the servable variants, and every other model figure has no estimate.

Tables and views

Pass a policy to a draw macro by name: one of the views above, or a CTE in your query. lift = reward / reward_alt − 1, headroom_lift = reward_oracle / reward_alt − 1, and headroom_captured is how much of the headroom the policy has captured, from 0 to 1. The averaged (non-_by_context) forms average rewards over contexts by weight first, then take the ratios.

Standard figures

The dashboard, CLI and agent skills derive their figures the same way. Intervals are central credible intervals, and the median is the point estimate.

Importance is a lift for design factors, context factors and the interaction alike: what optimizing that factor (or conditioning on that context factor, or choosing the design jointly) is worth. All three are on one scale and compare directly. They are not shares and do not add up to anything. Withhold one factor per query; two restrictions in one query can exceed memory on large models.

Example: the headline figures.

SELECT quantile_cont(lift, [0.025, 0.5, 0.975]) AS policy_lift,
       quantile_cont((lift + headroom_lift) / 2, [0.025, 0.5, 0.975]) AS ceiling_lift,
       avg((lift > 0)::DOUBLE) AS p_beats_reference,
       median(headroom_captured) AS progress
FROM policy_draws('thompson_policy', 'baseline_policy')

Example: what optimizing design factor $factor is worth.

SELECT quantile_cont(reward_oracle / reward - 1, [0.025, 0.5, 0.975]) AS lift
FROM oracle_draws(
  (SELECT list(factor) FROM context_factors),
  (SELECT list(factor) FROM design_factors WHERE factor <> $factor))

For a context factor, withhold it from the first list and pass every design factor in the second.

From the CLI, levered posterior query <optimization-id> --sql '<sql>' [--param name=value] [--version <v>] [--json] runs the same route.