---
title: "Get Matchup"
method: GET
path: "/api/v1/votes/matchup/{ranking_id}"
tags: ["Votes"]
---

# Get Matchup

`GET /api/v1/votes/matchup/{ranking_id}`

## Request

- Base URL: `https://app.aimrank.io` (the document declares no server; this is the origin it was published from)
- URL: `https://app.aimrank.io/api/v1/votes/matchup/{ranking_id}`
- Auth: none declared

Get a matchup for voting.

Strategies:
- adaptive: Auto-selects best strategy based on ranking maturity (RECOMMENDED)
- swiss: Swiss-system tournament pairing (fast convergence, rematch avoidance)
- random: Random pair selection
- balanced: Prefer evenly-matched pairs (better for accuracy)
- uncertainty: Prefer high-uncertainty entities (reduces RD faster)
- explore: AI-driven discovery - find novel matchups based on embeddings
- information_gain: Maximize expected information gain per vote (proper entropy formula)

## Path parameters

- `ranking_id` string, required

## Query parameters

- `strategy` 'adaptive' | 'swiss' | 'random' | 'balanced' | 'uncertainty' | 'explore' | 'information_gain'
- `pin` string, nullable: Serve exactly this pair, as 'entity_a_id,entity_b_id'. Used by shared challenge links so the recipient answers the SAME question ('I picked A over B — do you agree?'). Falls back to the normal strategy when either entity is missing, inactive, or not in this ranking — a stale link should still yield a votable pair.

## Response `200`

Successful Response

- MatchupResponse
  - `entity_a` object, required
  - `entity_b` object, required
  - `predicted_winner` string, required
  - `win_probability` number, required
  - `match_quality` number, required
  - `media_type` string
  - `user_streak` integer, nullable
  - `total_votes_on_matchup` integer

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/aimrank/apis/aimrank-api.md) · [All operations](https://skmtc.dev/aimrank/apis/aimrank-api/llms.txt) · [OpenAPI document](https://skmtc.dev/aimrank/apis/aimrank-api/revisions/3574d0aff459?raw)