---
title: "Upcoming football matches with predictions"
method: GET
path: "/v1/predictions/football/upcoming"
tags: ["predictions"]
---

# Upcoming football matches with predictions

`GET /v1/predictions/football/upcoming`

## Request

- Base URL: `https://api.predixsport.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.predixsport.com/v1/predictions/football/upcoming`
- Auth: none declared

Returns matches whose scheduled date falls in the inclusive window ``[today, today + days]``. The filter is a SQL ``BETWEEN`` against ``football_predictions_<league>.prediction_date`` — equivalent to ``prediction_date >= today AND prediction_date <= today + days``. ``today`` is the server's current UTC date at request time. A match scheduled for today itself is included. Without ``league``, all 12 league tables (5 top flights + 7 second divisions) are queried and merged. Returns ``{matches: [], count: 0}`` (HTTP 200) when no rows fall in the window — typically off-season. Use ``/v1/predictions/football/search`` for historical queries.

## Query parameters

- `league` 'serie_a' | 'premier_league' | 'la_liga' | 'bundesliga' | 'ligue_1' | 'championship' | 'league_one' | 'league_two' | 'segunda_division' | 'ligue_2' | 'bundesliga_2' | 'serie_b'
- `limit` integer
- `days` integer: Look-ahead horizon in days. Defines the upper bound of the inclusive window ``[today, today + days]``. Default 7, max 60.

## Headers

- `authorization` string, nullable

## Response `200`

Successful Response

- FootballUpcomingResponse
  - `matches` FootballUpcomingMatch[], required
    - `match_id` string, required
    - `sport` 'football'
    - `league` string, required: Customer-facing league code. 12 leagues: 5 top flights (serie_a, premier_league, la_liga, bundesliga, ligue_1) and 7 second divisions (championship, league_one, league_two, segunda_division, ligue_2, bundesliga_2, serie_b).
    - `prediction_date` string, date, required
    - `season` string, required
    - `home_team` string, required
    - `away_team` string, required
    - `probability_home_win` number, nullable: P(home win). Source: 1X2 softmax classifier.
    - `probability_draw` number, nullable: P(draw). Source: 1X2 softmax classifier (same as home_win / away_win).
    - `probability_away_win` number, nullable: P(away win). Source: 1X2 softmax classifier.
    - `probability_under_2_5` number, nullable: P(total goals ≤ 2). Source: INDEPENDENT over/under classifier — NOT derived from the 1X2 model.
    - `probability_over_2_5` number, nullable: P(total goals ≥ 3). Source: INDEPENDENT over/under classifier — NOT derived from the 1X2 model.
    - `predicted_result` string, nullable: Argmax of the 1X2 classifier (home / draw / away).
  - `count` integer, required

## Other responses

- `422`: Validation Error

---

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