# Merit engine & OzmaScore

Ozma ranks APIs with **objective merit signals** derived from real proxy usage — not ads or manual curation. Scores roll up every hour from `usage_events` into `provider_stats` and `score_snapshots` via the merit engine in `packages/merit`.

## Five axes (30-day window)

| Axis | Signal |
|------|--------|
| **Reliability** | Success rate × latency factor (Wilson lower bound) |
| **Retention** | Repeat payers / unique payers (Wilson; min sample thresholds) |
| **Adoption** | GMV + payer count (log-scaled; shrinkage on low volume) |
| **Value** | Successful calls per dollar, adjusted for refunds |
| **Momentum** | Paid calls in last 24h (hotness curve) |

Small samples shrink toward neutral priors so new APIs cannot instantly outrank established ones with sparse data.

## OzmaScore (0–100)

Category-normalized percentiles of each axis blend into a weighted score (reliability 30%, retention 25%, adoption 20%, value 15%, momentum 10%). Each API gets `rank_in_category` on snapshots.

## Search & leaderboards

Six public leaderboards — `top_grossing`, `most_used`, `most_reliable`, `best_value`, `trending`, `new_rising` — refresh on cron. **New & Rising** uses Thompson sampling for low-data APIs with reserved exploration slots.

When you search with a query, default sort `relevance` blends semantic match (~75%) with OzmaScore (~25%) among relevant candidates (merit ranking v2, default ON).

## Health & anti-gaming

Daily health probes suspend APIs after three consecutive upstream failures — suspended listings drop from merit rollups. Self-dealing (same org as consumer and provider) is excluded. Payer concentration caps reduce merit when one consumer dominates an API's usage.

Rankings are **earned from marketplace behavior** — transparent on every listing and API detail page.

## Learn more

- [Discover APIs](/docs/guides/discover-apis)
- [Provider profiles](/docs/guides/provider-profiles)