> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise.predexon.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Games
> Compact game/outcome discovery view backed by canonical sports tables
## Overview
Returns broad sports games with canonical outcomes. This endpoint is the compact discovery view: venues are summarized at the game level, and each outcome exposes the canonical `predexon_id` used for routing and lookup.
For per-venue execution detail, prices, token IDs, condition IDs, and market titles, use [`GET /v2/sports/markets`](/api-reference/sports/markets) or [`GET /v2/sports/outcomes/{predexon_id}`](/api-reference/sports/outcomes).
## Query Parameters
| Param | Type | Default | Description |
| ---------------- | ------ | --------------- | --------------------------------------------------------------------------------------- |
| `sport` | string | - | Filter by sport: `basketball`, `soccer`, `hockey`, `baseball`. |
| `league` | string | - | Filter by league code (e.g. `nba`, `epl`). See [league codes](/index#league-codes). |
| `status` | string | `open` | `open` or `closed`. |
| `game_date` | string | - | Exact date, `YYYY-MM-DD`. See [date conventions](/concepts/sports-markets#dates-times). |
| `game_date_from` | string | - | Inclusive lower bound, `YYYY-MM-DD`. |
| `game_date_to` | string | - | Inclusive upper bound, `YYYY-MM-DD`. |
| `search` | string | - | Case-insensitive search against market titles. |
| `sort_by` | string | `game_date_asc` | `game_date_asc` or `game_date_desc`. |
| `limit` | int | `50` | 1-200. |
| `pagination_key` | string | - | Opaque cursor from the previous response. Omit on the first request. |
### Pagination
Sports list endpoints use cursor pagination. Pass the returned `pagination.pagination_key` into the next request. Do not use offset-based pagination.
```json theme={null}
{
"pagination": {
"limit": 50,
"has_more": true,
"pagination_key": "eyJybyI6NTA..."
}
}
```
## Response Fields
### Game
| Field | Type | Description |
| ------------------ | ------- | ---------------------------------------------------------- |
| `game_id` | string | Canonical game identifier (e.g. `nba-atl-nyk-2026-04-18`). |
| `title` | string | Display title (e.g. `"Atlanta Hawks vs New York Knicks"`). |
| `league` | string | League code. |
| `league_name` | string | Human-readable league name. |
| `sport` | string | Sport name. |
| `game_date` | string | Calendar date, `YYYY-MM-DD`. |
| `status` | string | `"open"` or `"closed"`. |
| `venues_available` | int | Number of venues offering this game. |
| `total_volume` | number? | USD volume summed across all venues. |
| `total_liquidity` | number? | USD liquidity summed across all venues. |
| `outcomes[]` | array | One entry per tradeable side. |
### Outcome
| Field | Type | Description |
| ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `outcome` | string | Canonical outcome code (team code or `"draw"`). |
| `label` | string | Human-readable label. |
| `yes.predexon_id` | string | Canonical `predexon_id` for this outcome when buying YES. |
| `no.predexon_id` | string? | Canonical `predexon_id` for buying NO on that venue question/selection when an executable NO listing exists. In 2-way games this may equal the sibling YES outcome ID; in 3-way soccer it points to an explicit negation outcome such as "Draw does not happen." |
`predexon_id` is canonical across venues. The same team/draw outcome for the same game has one `predexon_id`, even when several venues list it.
`/games` is intentionally compact. It does not return venue-native identifiers. Use `/markets` for venue comparison and `/outcomes/{predexon_id}` for route resolution.
## Example
`GET /v2/sports/games?league=mlb&limit=1`
```json theme={null}
{
"games": [
{
"game_id": "mlb-ari-pit-2026-05-07",
"title": "Arizona Diamondbacks vs Pittsburgh Pirates",
"league": "mlb",
"league_name": "MLB",
"sport": "baseball",
"game_date": "2026-05-07",
"status": "open",
"venues_available": 3,
"total_volume": 895447.602333,
"total_liquidity": 40231.55,
"outcomes": [
{
"outcome": "ari",
"label": "Arizona Diamondbacks",
"yes": { "predexon_id": "px-xz7fw6lsywv2rnwr" },
"no": { "predexon_id": "px-c3dftfrdu5unmk3g" }
},
{
"outcome": "pit",
"label": "Pittsburgh Pirates",
"yes": { "predexon_id": "px-c3dftfrdu5unmk3g" },
"no": { "predexon_id": "px-xz7fw6lsywv2rnwr" }
}
]
}
],
"pagination": {
"limit": 1,
"has_more": true,
"pagination_key": "eyJybyI6MS..."
}
}
```
## When to Use This vs `/markets`
| Use Case | Endpoint |
| --------------------------------------------------------- | ----------------------------- |
| Trading UI — show compact game/outcome list | **`/games`** (this endpoint) |
| Order routing — find venue for a `predexon_id` | `GET /outcomes/{predexon_id}` |
| Arbitrage detection — compare prices across venues | `/markets` |
| Venue-specific metadata (market\_id, condition\_id, etc.) | `/markets` |
| Building a data feed with full venue detail | `/markets` |
## Caching
Responses are cached for 60 seconds.
## OpenAPI
````yaml GET /v2/sports/games
openapi: 3.1.0
info:
title: Predexon Enterprise API
description: Unified cross-venue prediction market discovery
version: 1.0.0
servers:
- url: https://api.predexon.com
security:
- apiKey: []
paths:
/v2/sports/games:
get:
tags:
- sports
summary: List Games
description: >-
Compact canonical sports game/outcome discovery view. Use
/v2/sports/markets for per-venue execution detail and prices.
operationId: list_games_aggregated_v2_sports_games_get
parameters:
- name: sport
in: query
required: false
schema:
type: string
enum:
- basketball
- soccer
- hockey
- baseball
description: Filter by sport.
- name: league
in: query
required: false
schema:
type: string
description: Filter by league code (e.g. nba, epl).
- name: status
in: query
required: false
schema:
type: string
default: open
enum:
- open
- closed
description: Market status.
- name: game_date
in: query
required: false
schema:
type: string
description: Exact game date (YYYY-MM-DD).
- name: game_date_from
in: query
required: false
schema:
type: string
description: Games on or after date (YYYY-MM-DD).
- name: game_date_to
in: query
required: false
schema:
type: string
description: Games on or before date (YYYY-MM-DD).
- name: search
in: query
required: false
schema:
type: string
description: Search game/market titles.
- name: sort_by
in: query
required: false
schema:
type: string
default: game_date_asc
enum:
- game_date_asc
- game_date_desc
description: Sort order.
- name: limit
in: query
required: false
schema:
type: integer
default: 50
minimum: 1
maximum: 200
description: Max games to return.
- name: pagination_key
in: query
required: false
schema:
type: string
description: Cursor from the previous response. Omit on the first request.
responses:
'200':
description: Successful response
content:
application/json:
schema: {}
example:
games:
- game_id: mlb-ari-pit-2026-05-07
title: Arizona Diamondbacks vs Pittsburgh Pirates
league: mlb
league_name: MLB
sport: baseball
game_date: '2026-05-07'
status: open
venues_available: 3
total_volume: 895447.602333
total_liquidity: 40231.55
outcomes:
- outcome: ari
label: Arizona Diamondbacks
'yes':
predexon_id: px-xz7fw6lsywv2rnwr
'no':
predexon_id: px-c3dftfrdu5unmk3g
- outcome: pit
label: Pittsburgh Pirates
'yes':
predexon_id: px-c3dftfrdu5unmk3g
'no':
predexon_id: px-xz7fw6lsywv2rnwr
pagination:
limit: 1
has_more: true
pagination_key: eyJybyI6MS...
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: >-
Data key provided by Predexon. The trading key used by the Order Router
on trade.predexon.com is a separate credential.
````