Search matches

GET /v1/matches

The workhorse list, filter on anything on the row

The workhorse of the API. Every filter composes, so you can ask for finished Premier League matches in 2024 that carry a kickoff price and sort them however you like. Cursor paged, so a page boundary stays stable while new matches arrive. Pass ids to ask for a known set: up to fifty match ids in one request, dash separated, with every other filter still applying. An id that does not decode is refused rather than skipped, so a response is never quietly short. Each match carries team_figures (xG, shots, corners, cards and possession, home and away), so a season can be compared without fetching every match.

Plan

This endpoint needs Free key. It works on the free key, which reads yesterday, as one whole day.

Parameters

ids string query

Up to 50 match ids in one request, separated by a dash. Every other filter still applies, so a set can be narrowed further. Each id costs one call against your rate limit, so this saves round trips rather than quota. An id that is not valid is refused rather than skipped: a response that quietly drops one looks complete and is not. e.g. mt_0CXSZRJ-mt_087EP2A

league_id string query

Restrict to one competition. Ids come from /v1/leagues: 39 is the English Premier League, 62 is Ligue 2. e.g. lg_24T9Z0G

country string query

Restrict to one country, by name as returned from /v1/countries. e.g. England

season integer query

Season by its starting year. A 2024/25 season is 2024. e.g. 2024

team_id string query

Matches involving this club, home or away. e.g. tm_1E5HXK9

date_from string query

Earliest kickoff date, inclusive. ISO YYYY-MM-DD, evaluated in UTC. e.g. 2024-08-01

date_to string query

Latest kickoff date, inclusive. e.g. 2024-08-31

status string query

Lifecycle filter: finished, scheduled, cancelled, postponed, abandoned, or one of the in-play states. e.g. finished

result string query

Full-time result: home, draw or away. e.g. home

has_prices boolean query

Only matches carrying an exchange price at kickoff. Useful when you are modelling and a match without a market is noise. e.g. true

surface string query

Restrict to matches played on a given surface: grass, artificial_turf or sand_pitch. Read from the ground rather than the match, so a stadium that resurfaces is corrected in one place. e.g. artificial_turf

venue string query

Restrict to home or away matches. Omit for both. e.g. home

limit integer query

Rows per page, 1–1000. Defaults to 100. e.g. 100

page integer query

Page number, 1-based. The response carries total, total_pages, next_page and prev_page, so a UI pager has everything it needs from one call. If you send both page and cursor, page wins. e.g. 2

cursor string query

Opaque cursor from meta.next_cursor. Pages by sort position rather than offset, so page 10,000 is as fast as page 1 and a new match arriving cannot shift the boundary. Pass it back unchanged; do not build or parse one yourself.

sort string query

Sort field, optionally prefixed with - for descending. Defaults to -kickoff_utc. e.g. kickoff_utc

Returns

data[].match_id string

Our id for the match. Stable: what you store today still resolves later.

data[].country_name string

The country the competition belongs to.

data[].league_name string

The competition's name.

data[].kickoff_utc integer

Kickoff, as a UTC timestamp.

data[].kickoff_date string

The kickoff date in UTC, YYYY-MM-DD.

data[].match_status string

Where the match stands: scheduled, in play by half, half time, finished, postponed, cancelled, abandoned, awarded or walkover.

data[].home_team_name string

The home side's name.

data[].away_team_name string

The away side's name.

data[].home_goals integer

The home side's goals: the final score, after extra time where played.

data[].away_goals integer

The away side's goals: the final score, after extra time where played.

data[].full_time_result empty in this example

home, draw or away, on the final score.

data[].home_league_position integer

The home side's place in the table before the match.

data[].away_league_position integer

The away side's place in the table before the match.

data[].away_travel_km integer

How far the away side travelled, in kilometres.

data[].home_kickoff_price number

The price for a home win at kickoff, as decimal odds.

data[].draw_kickoff_price number

The price for the draw at kickoff, as decimal odds.

data[].away_kickoff_price number

The price for an away win at kickoff, as decimal odds.

meta.data_as_of string

When the data behind this answer was last brought up to date.

meta.request_id string

This request's id, to quote to support.

meta.count integer

How many items are in this answer.

meta.next_cursor string

Pass it as cursor for the next page; empty on the last.

meta.page integer

This page's number.

meta.per_page integer

How many items a page holds.

meta.total integer

How many items match in all.

meta.total_pages integer

Total pages.

meta.next_page integer

Next page.

meta.prev_page empty in this example

Prev page.

Request

curl "https://api.footballsoccerapi.com/v1/matches?ids=mt_0CXSZRJ-mt_087EP2A&league_id=lg_24T9Z0G&country=England" \
  -H "X-API-Key: $FSAPI_KEY"

const res = await fetch("https://api.footballsoccerapi.com/v1/matches?ids=mt_0CXSZRJ-mt_087EP2A&league_id=lg_24T9Z0G&country=England", {
  headers: { "X-API-Key": process.env.FSAPI_KEY }
});
const { data, meta } = await res.json();

import os, requests

r = requests.get(
    "https://api.footballsoccerapi.com/v1/matches?ids=mt_0CXSZRJ-mt_087EP2A&league_id=lg_24T9Z0G&country=England",
    headers={"X-API-Key": os.environ["FSAPI_KEY"]},
)
data = r.json()["data"]

$ch = curl_init("https://api.footballsoccerapi.com/v1/matches?ids=mt_0CXSZRJ-mt_087EP2A&league_id=lg_24T9Z0G&country=England");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: {$key}"],
]);
$data = json_decode(curl_exec($ch), true)["data"];

Example response

A real row from the archive, fetched when this page rendered. Run it against your own key below.

200 OK application/json

{
    "data": [
        {
            "match_id": "mt_28QVFGW",
            "country_name": "Colombia",
            "league_name": "Primera A",
            "kickoff_utc": 1793228400,
            "kickoff_date": "2026-10-28",
            "match_status": "finished",
            "home_team_name": "Once Caldas",
            "away_team_name": "Alianza Valledupar",
            "home_goals": 1,
            "away_goals": 0,
            "full_time_result": null,
            "home_league_position": 7,
            "away_league_position": 16,
            "away_travel_km": 650,
            "home_kickoff_price": 1.58,
            "draw_kickoff_price": 3.7,
            "away_kickoff_price": 6.25
        },
        {
            "match_id": "mt_1SGZZ85",
            "country_name": "Germany",
            "league_name": "DFB Pokal",
            "kickoff_utc": 1793216700,
            "kickoff_date": "2026-10-28",
            "match_status": "finished",
            "home_team_name": "Hannover 96",
            "away_team_name": "1. FC Kaiserslautern",
            "home_goals": 0,
            "away_goals": 2,
            "full_time_result": "away",
            "home_league_position": null,
            "away_league_position": null,
            "away_travel_km": 354,
            "home_kickoff_price": 1.66,
            "draw_kickoff_price": 4.2,
            "away_kickoff_price": 4.4
        }
    ],
    "meta": {
        "data_as_of": "2026-10-29T04:32:57Z",
        "request_id": "01J9QW3C7M4KX2VB",
        "count": 2,
        "next_cursor": "MTcyOTMzNzQwMDoxMjA4MDk5",
        "page": 1,
        "per_page": 100,
        "total": 380,
        "total_pages": 4,
        "next_page": 2,
        "prev_page": null
    }
}

Run it live

Paste your key and fire the real request. The key is kept in this browser only and never sent anywhere but the API.

Your API key Get a key

ids league_id country season team_id date_from date_to status result has_prices surface venue limit page cursor sort

GET

← All endpoints Get a free key →