---
title: "Queries a benchmark's image matchups — a page of compared image pairs with how the responses
 split between them."
method: GET
path: "/benchmark/{benchmarkId}/matchups/query"
tags: ["Benchmark"]
---

# Queries a benchmark's image matchups — a page of compared image pairs with how the responses
 split between them.

`GET /benchmark/{benchmarkId}/matchups/query`

An item is one image pair as one leaderboard saw it, so a pair compared on several leaderboards
 comes back once per leaderboard and the boards' verdicts on it can be read side by side.
 Ordering (sigma by default) ranks the matchups themselves — sigma being how far apart the two
 images' records over all of their comparisons on the prompt sit, in standard errors of their
 logit gap — where the prompt-ratings query ranks prompts by their most decisive matchup. Filters
 use that query's field set, applied to the votes a matchup is tallied from, plus
 WinnerParticipantId and LooserParticipantId, which select matchups by which side
 won the whole matchup; those two are only accepted as top-level and leaves, and a tied
 matchup matches neither. Matchups of leaderboards excluded from the benchmark overall are never
 returned.
 sides holds exactly two images, the one that took more responses first, and their
 responses sum to the matchup's. Each side carries its theta — the pooled per-image
 record sigma is derived from. extremeness and the winning side are always read off the
 raw counts, and sigma/theta are always weighted by annotator reliability;
 useWeightedScoring changes only each side's wins.

## Path parameters

- `benchmarkId` string, required

## Query parameters

- `useWeightedScoring` boolean
- `groupBy` 'Image' | 'Participant' — What each rated entry of a prompt represents.
- `page` integer
- `page_size` integer
- `sort` string[]
- `country` object
  - `eq` string
  - `neq` string
  - `gt` string
  - `gte` string
  - `lt` string
  - `lte` string
  - `contains` string
  - `starts_with` string
  - `ends_with` string
  - `in` string[]
  - `not_contains` string
- `language` object
  - `eq` string
  - `neq` string
  - `gt` string
  - `gte` string
  - `lt` string
  - `lte` string
  - `contains` string
  - `starts_with` string
  - `ends_with` string
  - `in` string[]
  - `not_contains` string
- `gender` object
  - `eq` string
  - `neq` string
  - `gt` string
  - `gte` string
  - `lt` string
  - `lte` string
  - `contains` string
  - `starts_with` string
  - `ends_with` string
  - `in` string[]
  - `not_contains` string
- `age_bucket` object
  - `eq` string
  - `neq` string
  - `gt` string
  - `gte` string
  - `lt` string
  - `lte` string
  - `contains` string
  - `starts_with` string
  - `ends_with` string
  - `in` string[]
  - `not_contains` string
- `occupation` object
  - `eq` string
  - `neq` string
  - `gt` string
  - `gte` string
  - `lt` string
  - `lte` string
  - `contains` string
  - `starts_with` string
  - `ends_with` string
  - `in` string[]
  - `not_contains` string
- `tags` object
  - `eq` string
  - `neq` string
  - `gt` string
  - `gte` string
  - `lt` string
  - `lte` string
  - `contains` string
  - `starts_with` string
  - `ends_with` string
  - `in` string[]
  - `not_contains` string
- `participant_id` object
  - `eq` string
  - `neq` string
  - `gt` string
  - `gte` string
  - `lt` string
  - `lte` string
  - `contains` string
  - `starts_with` string
  - `ends_with` string
  - `in` string[]
  - `not_contains` string
- `leaderboard_id` object
  - `eq` string
  - `neq` string
  - `gt` string
  - `gte` string
  - `lt` string
  - `lte` string
  - `contains` string
  - `starts_with` string
  - `ends_with` string
  - `in` string[]
  - `not_contains` string
- `run_id` object
  - `eq` string
  - `neq` string
  - `gt` string
  - `gte` string
  - `lt` string
  - `lte` string
  - `contains` string
  - `starts_with` string
  - `ends_with` string
  - `in` string[]
  - `not_contains` string
- `prompt_identifier` object
  - `eq` string
  - `neq` string
  - `gt` string
  - `gte` string
  - `lt` string
  - `lte` string
  - `contains` string
  - `starts_with` string
  - `ends_with` string
  - `in` string[]
  - `not_contains` string
- `voted_at` object
  - `eq` string
  - `neq` string
  - `gt` string
  - `gte` string
  - `lt` string
  - `lte` string
  - `contains` string
  - `starts_with` string
  - `ends_with` string
  - `in` string[]
  - `not_contains` string
- `winner_participant_id` object
  - `eq` string
  - `neq` string
  - `gt` string
  - `gte` string
  - `lt` string
  - `lte` string
  - `contains` string
  - `starts_with` string
  - `ends_with` string
  - `in` string[]
  - `not_contains` string
- `looser_participant_id` object
  - `eq` string
  - `neq` string
  - `gt` string
  - `gte` string
  - `lt` string
  - `lte` string
  - `contains` string
  - `starts_with` string
  - `ends_with` string
  - `in` string[]
  - `not_contains` string
- `logic` 'and' | 'or'

## Response `200`

OK

- QueryMatchupsByBenchmarkEndpointOutput — The queried image matchups output.
  - `items` QueryMatchupsByBenchmarkEndpointOutputMatchup[], required — The matchups of this page, in the requested order.
    - `leaderboard` QueryMatchupsByBenchmarkEndpointOutputLeaderboard, required
      - `id` string, required
      - `name` string, nullable
    - `promptIdentifier` string, required
    - `prompt` object, nullable
      - `id` string, required
      - `english` string, nullable
      - `original` string, nullable
      - `asset` union
        - IAssetFileAsset
          - `_t` 'FileAsset', required
          - `fileName` string, required
          - `metadata` MetadataModelCollection, required
          - `identifier` string, required
        - IAssetMultiAsset
          - `_t` 'MultiAsset', required
          - `assets` IAsset[], required
            - union
              - …
          - `metadata` MetadataModelCollection, required
          - `identifier` string, required
        - IAssetNullAsset
          - `_t` 'NullAsset', required
          - `metadata` MetadataModelCollection, required
          - `identifier` string, required
        - IAssetTextAsset
          - `_t` 'TextAsset', required
          - `text` string, required
          - `metadata` MetadataModelCollection, required
          - `identifier` string, required
    - `sides` QueryMatchupsByBenchmarkEndpointOutputSide[], required
      - `sampleId` string, required
      - `participantId` string, required
      - `participantName` string, nullable
      - `asset` union
        - IAssetFileAsset
          - `_t` 'FileAsset', required
          - `fileName` string, required
          - `metadata` MetadataModelCollection, required
          - `identifier` string, required
        - IAssetMultiAsset
          - `_t` 'MultiAsset', required
          - `assets` IAsset[], required
            - union
              - …
          - `metadata` MetadataModelCollection, required
          - `identifier` string, required
        - IAssetNullAsset
          - `_t` 'NullAsset', required
          - `metadata` MetadataModelCollection, required
          - `identifier` string, required
        - IAssetTextAsset
          - `_t` 'TextAsset', required
          - `text` string, required
          - `metadata` MetadataModelCollection, required
          - `identifier` string, required
      - `responses` integer, required
      - `wins` number, double, required
      - `theta` number, double, required
    - `responses` integer, required
    - `sigma` number, double, required
    - `extremeness` number, double, required
    - `latestVotedAt` string, date-time, required
  - `total` integer, required — The number of matchups the filter leaves — the paging total.
  - `page` integer, required — The 1-based page index.
  - `pageSize` integer, required — The page size in matchups.
  - `corpus` QueryMatchupsByBenchmarkEndpointOutputCorpus, required
    - `totalResponses` integer, required

## Other responses

- `400` — Bad Request
- `401` — Unauthenticated
- `403` — Forbidden

---

[API](https://skmtc.dev/rapidata/apis/rapidata-api.md) · [All operations](https://skmtc.dev/rapidata/apis/rapidata-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/rapidata/rapidata-api/revisions/4ee3e6f5e4f4/schema)