---
title: "AI Recommendation Index — category rankings"
method: GET
path: "/api/index/{slug}"
tags: ["AI Index"]
---

# AI Recommendation Index — category rankings

`GET /api/index/{slug}`

## Request

- Base URL: `https://api.orbator.io`
- URL: `https://api.orbator.io/api/index/{slug}`
- Auth: one of:
  - none
  - API key in header `X-Api-Key`
  - HTTP bearer

Per-category recommendation share, average position, per-engine breakdown and 4-week trend for every product AI engines recommend in the category. Categories with fewer runs than the minimum sample return status "insufficient_data" instead of noisy numbers.

## Path parameters

- `slug` string, required

## Query parameters

- `by_intent` '1'

## Response `200`

Category index payload (share, trend, per-engine breakdown, sample size, methodology URL)

- CategoryIndex
  - `status` 'ok' | 'insufficient_data'
  - `category` object
    - `id` string, uuid
    - `slug` string
    - `label` string
  - `window` IndexWindow: 4-week rolling measurement window
    - `weeks` integer
    - `from` string, date-time
    - `to` string, date-time
    - `prior_from` string, date-time: Start of the prior window trends compare against
  - `sample_size` integer: Answer runs in the current window
  - `prior_sample_size` integer
  - `min_sample` integer: Runs required before numbers are published
  - `engine_samples` object: Per-engine audit trail (MTH-006): current-window run counts (they sum to sample_size) plus each engine's newest run date across the current + prior windows — rotation lag is disclosed, not hidden.
  - `volatility` object: Ranking-wide stability score (MTH-006): median of the top entries' MTH-002 volatility scores, rounded toward the worse level; null with no scored history.
    - `score` 'stable' | 'moderate' | 'volatile', nullable
  - `methodology_url` string
  - `license` string
  - `entries` CategoryIndexEntry[]
    - `index_product_id` string, uuid
    - `name` string
    - `domain` string, nullable
    - `recommendation_share` number: % of runs in the window recommending this product
    - `ci_low` number, nullable: Lower bound of the 95% Wilson confidence interval on recommendation_share (STR-001)
    - `ci_high` number, nullable: Upper bound of the 95% Wilson confidence interval on recommendation_share (STR-001)
    - `mention_runs` number: Answers in the window recommending this product (CI numerator)
    - `first_rec_runs` number: Recommending answers where this product was named first
    - `first_rec_rate` number, nullable: % of this product's recommending answers where it was the #1 recommendation
    - `avg_position` number, nullable: Average 1-based rank when answers are lists
    - `per_engine` object
    - `trend` object, nullable
      - `direction` 'up' | 'down' | 'flat' | 'new'
      - `delta` number: Share change vs the prior window, in percentage points
      - `prior_share` number, nullable
    - `is_orbator_customer` boolean: Disclosure flag — measurement is unaffected by customer status
    - `product_facts` object, nullable: Sourced facts grouped by fact type (pricing, feature, platform, integration). Present only when the product has facts; every fact carries source_url + last_verified_at. Same store as /api/compare/{pair}.
    - `best_for` object, nullable: Data-derived buyer use-case this product over-indexes on: the category prompt where it is recommended most strongly, straight from the answer corpus (no model calls). Present only when the signal clears the sample + over-index guardrails; omitted otherwise.
      - `prompt` string: The verbatim buyer question (the use-case)
      - `share` number: % of that prompt's answers recommending the product
      - `mentions` integer
      - `runs` integer: Answer runs for that prompt in the window
  - `intent_shares` IntentShareGroup[]: Present only when requested with ?by_intent=1: recommendation shares grouped by the buyer prompt's intent, so cuts can say "best for X" with data behind it. Runs whose prompt no longer matches any current category prompt group under intent "other".
    - `intent` string: Prompt intent, e.g. best_in_category, alternatives, problem_solving; "other" for unmatched prompts
    - `runs` integer: Answer runs for this intent in the window
    - `entries` object[]
      - `index_product_id` string, uuid
      - `name` string
      - `domain` string, nullable
      - `mentions` integer
      - `share` number: % of this intent's runs recommending the product
      - `avg_position` number, nullable
  - `editorial` EditorialSection[]: Editorial sections written from this window's measured data only (the page's own entries, per-engine shares, mention breakdown, sourced facts, archive). Rows with review_status "generated" are unreviewed and disclosed as such on the page; "approved" rows passed founder review; rejected rows are never served. Empty until the category's enrichment batch is released.
    - `id` string, uuid
    - `section` 'how_to_choose' | 'top_products' | 'engine_disagreement' | 'what_moved'
    - `body_md` string: Markdown paragraphs; every figure is traceable to the window's data
    - `window_to` string, date: End of the 4-week window the section was written from
    - `review_status` 'generated' | 'approved'
    - `generated_at` string, date-time

## Other responses

- `404`: Unknown or unpublished category
- `429`: Hourly quota exceeded for the current tier. Retry after the Retry-After header.

---

[API](https://skmtc.dev/orbator/apis/orbator-public-api.md) · [All operations](https://skmtc.dev/orbator/apis/orbator-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/orbator/apis/orbator-public-api/revisions/7d1cf20c2163?raw)