---
title: "List all market definitions"
method: GET
path: "/api/v2/markets"
tags: ["V2 Markets"]
---

# List all market definitions

`GET /api/v2/markets`

## Request

- Base URL: `https://therundown.io`
- URL: `https://therundown.io/api/v2/markets`
- Auth: API key in header `X-TheRundown-Key`

Returns the canonical market catalog with classification, sport
membership and an in-play-period flag, ordered by market ID. This
endpoint returns all matching definitions in one array.

All filters are optional and AND-combined; comma-separated values within
a filter are OR-combined. Omitting filters returns all definitions.
Uncatalogued markets use class=special, family=other and settlement=event;
scope has no default. A sport_id filter selects markets but preserves
each market's full sorted sports array.

## Query parameters

- `class` string
- `family` string
- `scope` string
- `settlement` string
- `sport_id` integer

## Response `200`

Market catalog definitions, optionally filtered

- MarketDefinition[]
  - `id` integer
  - `name` string
  - `description` string
  - `short_description` string
  - `line_value_is_participant` boolean: If true, the selection is carried by the participant and line values may be placeholders or labels. If false, the line value is meaningful and should be displayed when present.
  - `proposition` boolean: Whether this is a proposition/prop market
  - `period_id` integer, nullable: Associated period. 0=Full Game, 1=1st Half, 2=2nd Half, 3-6=Quarters/periods, 7=Live Full Game, 13-18=Live periods. For tennis, 3/4 represent prematch Set 1/Set 2 and 15/16 represent live Set 1/Set 2.
  - `live_variant_id` integer, nullable: ID of the live/in-play variant of this market
  - `updated_at` string, date-time
  - `class` string, required: Market classification. Defaults to special when no catalog entry exists. The response may contain values outside the current filter vocabulary.
  - `family` string, required: Market family. Defaults to other when no catalog entry exists. The response may contain values outside the current filter vocabulary.
  - `scope` string: What the outcome refers to. Omitted when no scope is recorded; no default. The response may contain values outside the current filter vocabulary.
  - `display_group` 'main' | 'game' | 'team' | 'player': Optional display-group override. Omitted when absent or outside the listed values.
  - `settlement` string, required: When the market settles. Defaults to event when no catalog entry exists. The response may contain values outside the current filter vocabulary.
  - `live` boolean, required: True for a definition whose period_id is an in-play period.
  - `sports` integer[], required: Full sport membership, sorted by sport ID. Always an array, empty when no membership is available. A sport_id filter does not trim it.

## Other responses

- `400`: Invalid catalog filter token or sport_id. An enum-filter error lists its accepted vocabulary.
- `503`: Returned for sport_id-filtered requests only while sport membership is temporarily undeterminable and no confirmed state is available.

## Changes

- **2026-11-05** `b1735c57a340`: 14 info
  - added the new optional `query` request parameter `class`
  - added the new optional `query` request parameter `family`
  - added the new optional `query` request parameter `scope`
  - added the new optional `query` request parameter `settlement`
  - …10 more

[Operation history](https://skmtc.dev/therundown/apis/therundown-sports-api/changes/api/v2/markets/get.md)

---

[API](https://skmtc.dev/therundown/apis/therundown-sports-api.md) - [All operations](https://skmtc.dev/therundown/apis/therundown-sports-api/llms.txt) - [OpenAPI document](https://skmtc.dev/therundown/apis/therundown-sports-api/revisions/b1735c57a340?raw)