List competition matches

Returns upcoming, verified historical, or combined match summaries for one selected competition. Starter includes up to 90 rolling days of history, with a maximum 31-day window per request.

Request

GET /v1/leagues/{code}/matches

Plan	Authentication	Cache	Units	Rows
Starter	`X-API-Key`	Private, 60 seconds; ETag and If-None-Match supported.	1	Number of match summaries returned

Parameters

Name	Location	Required	Description
`code`	path	yes	Competition code returned by GET /v1/leagues.
`include`	query	no	Use include=upcoming (default), include=past, or include=all. Past and all return only verified pre-match snapshots inside the Starter history entitlement.
`start`	query	no	First local API date in YYYY-MM-DD.
`days`	query	no	Window size in days, 1 to 31. Omit it with include=past to use the automatic history window min(history_entitlement_days, 31); include=upcoming and include=all keep the default of 14. An explicit value is never silently truncated: a window beyond the entitlement or beyond 31 days is rejected.
`limit`	query	no	Maximum 1 to 500 summaries; default 200.
`cursor`	query	no	Opaque deterministic continuation cursor returned as next_cursor.

Example

curl -sS "https://api.foresportia.com/v1/leagues/FIN/matches?include=upcoming&days=14&limit=100" \
  -H "X-API-Key: $FORESPORTIA_API_KEY"

Verified history

curl -sS \
  -H "X-API-Key: ${API_KEY}" \
  -H "Accept: application/json" \
  "https://api.foresportia.com/v1/leagues/CHN/matches?include=past&days=7&limit=100"

Retrieve up to 90 days in slices

Each request is limited to 31 days. Follow next_cursor when it is not null before moving to the next date slice.

# The start parameter is a real YYYY-MM-DD API parameter. Move it by at most 31 days per call.
curl -sS -H "X-API-Key: ${API_KEY}" "https://api.foresportia.com/v1/leagues/CHN/matches?include=past&start=2026-05-01&days=31&limit=100"
curl -sS -H "X-API-Key: ${API_KEY}" "https://api.foresportia.com/v1/leagues/CHN/matches?include=past&start=2026-06-01&days=31&limit=100"
curl -sS -H "X-API-Key: ${API_KEY}" "https://api.foresportia.com/v1/leagues/CHN/matches?include=past&start=2026-07-02&days=28&limit=100"

Response

{
  "league": {
    "code": "FIN",
    "name": "Veikkausliiga",
    "country": "Finland"
  },
  "catalog_status": "selectable",
  "activity_status": "active",
  "matches_available": 2,
  "matches_returned": 2,
  "future_matches_available": 2,
  "historical_matches_available": 1,
  "history_entitlement_days": 90,
  "history_available_from": "2026-07-14T13:35:00Z",
  "next_cursor": null,
  "date_range": {
    "start": "2026-10-17",
    "end": "2026-10-30",
    "include": "upcoming"
  },
  "timezone": "Europe/Paris",
  "source": "Foresportia",
  "data_version": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  "matches": [
    {
      "id": "fsm:v1:a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
      "kickoff": "2026-10-17T16:00:00Z",
      "kickoff_local": "2026-10-17T18:00:00+02:00",
      "league": {
        "code": "FIN",
        "name": "Veikkausliiga",
        "country": "Finland"
      },
      "home_team": "Riverton FC",
      "away_team": "Northbridge United",
      "probabilities": {
        "home": 0.58,
        "draw": 0.25,
        "away": 0.17
      },
      "confidence": {
        "score": 0.72
      },
      "likely_scores": [
        {
          "score": "2-0",
          "probability": 0.13
        },
        {
          "score": "1-0",
          "probability": 0.12
        }
      ],
      "markets": {
        "btts": 0.49,
        "over_2_5": 0.56,
        "under_2_5": 0.44,
        "dnb_home": 0.773333,
        "dnb_away": 0.226667,
        "double_chance_1x": 0.83,
        "double_chance_x2": 0.42,
        "double_chance_12": 0.75
      },
      "context": {
        "friendly": false,
        "knockout": false,
        "group_stage": false,
        "first_leg": false,
        "second_leg": false,
        "final": false,
        "neutral_venue": false,
        "stage": "Regular season"
      },
      "status": "scheduled",
      "pick": {
        "outcome": "home",
        "probability": 0.58
      }
    },
    {
      "id": "fsm:v1:b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2",
      "kickoff": "2026-10-17T18:30:00Z",
      "kickoff_local": "2026-10-17T20:30:00+02:00",
      "league": {
        "code": "FIN",
        "name": "Veikkausliiga",
        "country": "Finland"
      },
      "home_team": "Harbor Athletic",
      "away_team": "Oakfield City",
      "probabilities": {
        "home": 0.31,
        "draw": 0.29,
        "away": 0.4
      },
      "confidence": {
        "score": 0.62
      },
      "likely_scores": [
        {
          "score": "1-2",
          "probability": 0.11
        },
        {
          "score": "1-1",
          "probability": 0.1
        }
      ],
      "markets": {
        "btts": 0.57,
        "over_2_5": 0.51,
        "under_2_5": 0.49,
        "dnb_home": 0.43662,
        "dnb_away": 0.56338,
        "double_chance_1x": 0.6,
        "double_chance_x2": 0.69,
        "double_chance_12": 0.71
      },
      "context": {
        "friendly": false,
        "knockout": false,
        "group_stage": false,
        "first_leg": false,
        "second_leg": false,
        "final": false,
        "neutral_venue": false,
        "stage": "Regular season"
      },
      "status": "scheduled",
      "pick": {
        "outcome": "away",
        "probability": 0.4
      }
    }
  ]
}

Response counters

Field	Meaning
`matches_returned`	Number of match rows returned by this request.
`future_matches_available`	General future availability for the selected competition.
`historical_matches_available`	Verified historical rows currently available inside the client entitlement.
`history_entitlement_days`	Maximum rolling historical entitlement for the plan; 90 for Starter v1.
`history_available_from`	Earliest verified snapshot currently present in the promoted release; nullable while history accumulates.
`next_cursor`	Opaque deterministic continuation cursor, or null when the page is complete.
`matches_available`	Compatibility alias for future_matches_available; it does not describe the current filtered response.

Historical match fields

Field	Meaning
`status`	final for a completed historical match.
`result_score`	Verified final score, formatted as home-away.
`probabilities`	The 1X2 probabilities published before kickoff; they are not recalculated from the result.
`pick`	The outcome and probability selected before kickoff; no correctness badge is added.

Historical response

{
  "league": {
    "code": "CHN",
    "name": "Chinese Super League",
    "country": "China"
  },
  "catalog_status": "selectable",
  "activity_status": "active",
  "matches_available": 7,
  "matches_returned": 1,
  "future_matches_available": 7,
  "historical_matches_available": 1,
  "history_entitlement_days": 90,
  "history_available_from": "2026-07-14T13:35:00Z",
  "next_cursor": null,
  "date_range": {
    "start": "2026-07-08",
    "end": "2026-07-14",
    "include": "past"
  },
  "timezone": "Europe/Paris",
  "source": "Foresportia",
  "data_version": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  "matches": [
    {
      "id": "fsm:v1:c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3",
      "kickoff": "2026-07-12T11:35:00Z",
      "kickoff_local": "2026-07-12T13:35:00+02:00",
      "league": {
        "code": "CHN",
        "name": "Chinese Super League",
        "country": "China"
      },
      "home_team": "Harbor Athletic",
      "away_team": "Riverton FC",
      "probabilities": {
        "home": 0.47,
        "draw": 0.28,
        "away": 0.25
      },
      "confidence": {
        "score": 0.64
      },
      "likely_scores": [
        {
          "score": "2-1",
          "probability": 0.12
        }
      ],
      "markets": {
        "btts": 0.55,
        "over_2_5": 0.52,
        "under_2_5": 0.48,
        "dnb_home": 0.652778,
        "dnb_away": 0.347222,
        "double_chance_1x": 0.75,
        "double_chance_x2": 0.53,
        "double_chance_12": 0.72
      },
      "context": {
        "friendly": false,
        "knockout": false,
        "group_stage": false,
        "first_leg": false,
        "second_leg": false,
        "final": false,
        "neutral_venue": false,
        "stage": "Regular season"
      },
      "status": "final",
      "result_score": "3-2",
      "pick": {
        "outcome": "home",
        "probability": 0.47
      }
    }
  ]
}

matches_available remains a compatibility alias for future_matches_available. Use matches_returned for the current response. An empty matches array for a past window means that no verified historical row is available for that competition and period; it does not mean history is unsupported.

Empty response

{
  "league": {
    "code": "BEL",
    "name": "Belgian Pro League",
    "country": "Belgium"
  },
  "catalog_status": "selectable",
  "activity_status": "unavailable",
  "matches_available": 0,
  "matches_returned": 0,
  "future_matches_available": 0,
  "historical_matches_available": 0,
  "history_entitlement_days": 90,
  "history_available_from": "2026-07-14T13:35:00Z",
  "next_cursor": null,
  "date_range": {
    "start": "2026-10-17",
    "end": "2026-10-30",
    "include": "upcoming"
  },
  "timezone": "Europe/Paris",
  "source": "Foresportia",
  "data_version": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  "matches": []
}

Errors and limits

400 invalid include, date, days, or limit
401 missing or invalid API key
403 competition_not_selected
404 competition_not_found
429 quota or concurrency limit
503 Starter store unavailable

See Errors for the full list, and Quotas for the limits that apply to every route.

New to this route? The football dashboard tutorial calls it end to end and charts the results.

↑ Back to top Back to contents