---
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 (extremeness by default) ranks the matchups themselves — extremeness being how far the
 split sits from a coin flip, in standard deviations — 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. extremeness and the winning side are always read
 off the raw counts; 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
    - `responses` integer, 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.net/rapidata/apis/rapidata-api.md) · [All operations](https://skmtc.net/rapidata/apis/rapidata-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/rapidata/rapidata-api/revisions/fdb89a6eb2fb/schema)