A club's matches

GET /v1/teams/{id}/matches

Every match a club has played

Every match a club has played, optionally narrowed by season or to home or away only.

Plan

This endpoint needs Archive. Calling it on a lower plan returns a 403 naming the plan it needs and a link to pricing, never a bare refusal.

Parameters

team_id string path required

The club id. e.g. tm_1E5HXK9

season integer query

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

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.

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/teams/tm_1E5HXK9/matches?season=2024&venue=home&limit=100" \
  -H "X-API-Key: $FSAPI_KEY"

const res = await fetch("https://api.footballsoccerapi.com/v1/teams/tm_1E5HXK9/matches?season=2024&venue=home&limit=100", {
  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/teams/tm_1E5HXK9/matches?season=2024&venue=home&limit=100",
    headers={"X-API-Key": os.environ["FSAPI_KEY"]},
)
data = r.json()["data"]

$ch = curl_init("https://api.footballsoccerapi.com/v1/teams/tm_1E5HXK9/matches?season=2024&venue=home&limit=100");
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

team_id required season venue limit page cursor

GET

← All endpoints Get a free key →