Match History :: Football API

Here you can discover how to tap our historical football API endpoint and pull information on past matches that have wrapped up.

The history football API endpoint handles team names across multiple languages. To dig deeper into this, work through our documentation on language support.

On this page, we demostrate out how to obtain the list of football matches and scores played back in time. We also cover the options at your disposal to filter and page through our historical football data. Matches are returned in descending order, from the most recently finished match back to the earliest in history.

NOTE: the id of the match in the history football API endpoint matches the id used by the live scores API endpoint. That id differs from the id in the football fixtures API endpoint. That is why the fixture_id field exists here, linking a fixture to a match that has finished. When the fixture_id value is empty or 0, no fixture existed for this match before it kicked off.

ENDPOINT

To pull the full list of historical match data from our football API, simply call the URL shown below. We carry historical data for 400+ national competitions, cup matches, and international leagues spanning the globe.

GET:

Check this Football API endpoint in our postman collection. Download it now!

PARAMETERS

The football API history endpoint allows several parameters that you can apply to filter the football data and page through it as you see fit. Those parameters appear in the table below. You may combine them or use each one on its own.

Name	Type	Example	Description
competition_id	number\|string	1,2	The `id` of the competition whose historical football matches you are after. You can grab the `competition_id` from the competition list API endpoint. Filtering by several competitions is possible when you separate their ids with commas.
from	date	2018-05-15	Fetch past matches starting from this date onward.
lang	string	ru	A two letter ISO 639-1 language code. The full list of supported languages lives on our data languages documentation page.
page	number	3	Should multiple pages exist, this parameter lets you jump to a specific page.
team_id	number	19,7	The `id` of the team whose past scores you need. If you like, filter by several team ids separated by commas.
to	date	2018-05-15	Fetch past match data up to and including this date.

RESPONSE

A response to a request carries at most 30 past match records in total for the parameters supplied in the query.

{
    "success": true,
    "data": {
        "match": [
            {
                "time": "FT",
                "added": "2026-10-13 00:45:14",
                "id": 738590,
                "competition": {
                    "id": 406,
                    "is_cup": false,
                    "is_league": true,
                    "tier": 2,
                    "active": true,
                    "name": "Segunda Division",
                    "national_teams_only": false,
                    "has_groups": true
                },
                "away": {
                    "name": "Alianza Universidad",
                    "logo": "https:\/\/cdn.football-api.com\/teams\/4112.png",
                    "id": 4112,
                    "country_id": 52,
                    "stadium": "Estadio Heraclio Tapia Le\u00f3n"
                },
                "country": {
                    "fifa_code": "PER",
                    "name": "Peru",
                    "flag": "PER.png",
                    "uefa_code": "",
                    "id": 52,
                    "is_real": true
                },
                "status": "FINISHED",
                "fixture_id": 1902212,
                "scheduled": "01:01",
                "round": "3",
                "last_changed": "2026-10-13 02:57:23",
                "date": "2026-10-13",
                "home": {
                    "name": "Carlos A. Mannucci",
                    "logo": "https:\/\/cdn.football-api.com\/teams\/4080.png",
                    "id": 4080,
                    "country_id": 52,
                    "stadium": "Estadio Mario Orezzole"
                },
                "federation": null,
                "group_id": null,
                "location": "Estadio Mario Orezzole",
                "odds": {
                    "pre": {
                        "1": 1.6100000000000000976996261670137755572795867919921875,
                        "2": 4.70000000000000017763568394002504646778106689453125,
                        "X": 3.5
                    },
                    "live": {
                        "1": 1.04000000000000003552713678800500929355621337890625,
                        "2": 1.0100000000000000088817841970012523233890533447265625,
                        "X": 11
                    }
                },
                "outcomes": {
                    "half_time": "1",
                    "full_time": "1",
                    "extra_time": null,
                    "penalty_shootout": null
                },
                "scores": {
                    "score": "3 - 1",
                    "ht_score": "2 - 0",
                    "ft_score": "3 - 1",
                    "et_score": "",
                    "ps_score": ""
                }
            },
            {
                "time": "FT",
                "added": "2026-10-12 23:45:14",
                "id": 738589,
                "competition": {
                    "id": 95,
                    "is_cup": false,
                    "is_league": true,
                    "tier": 2,
                    "active": true,
                    "name": "Serie B",
                    "national_teams_only": false,
                    "has_groups": true
                },
                "away": {
                    "name": "Ceara",
                    "logo": "https:\/\/cdn.football-api.com\/teams\/1652.png",
                    "id": 1652,
                    "country_id": 16,
                    "stadium": "Est\u00e1dio Governador Pl\u00e1cido Aderaldo Castelo"
                },
                "country": {
                    "fifa_code": "BRA",
                    "name": "Brazil",
                    "flag": "BRA.png",
                    "uefa_code": "",
                    "id": 16,
                    "is_real": true
                },
                "status": "FINISHED",
                "fixture_id": 1851451,
                "scheduled": "00:00",
                "round": "33",
                "last_changed": "2026-10-13 01:53:44",
                "date": "2026-10-12",
                "home": {
                    "name": "Botafogo SP",
                    "logo": "https:\/\/cdn.football-api.com\/teams\/3235.png",
                    "id": 3235,
                    "country_id": 16,
                    "stadium": "Est\u00e1dio Santa Cruz"
                },
                "federation": null,
                "group_id": 4593,
                "location": "Est\u00e1dio Santa Cruz",
                "odds": {
                    "pre": {
                        "1": 2.20000000000000017763568394002504646778106689453125,
                        "2": 3.29999999999999982236431605997495353221893310546875,
                        "X": 3.20000000000000017763568394002504646778106689453125
                    },
                    "live": {
                        "1": null,
                        "2": null,
                        "X": null
                    }
                },
                "outcomes": {
                    "half_time": "X",
                    "full_time": "1",
                    "extra_time": null,
                    "penalty_shootout": null
                },
                "scores": {
                    "score": "1 - 0",
                    "ht_score": "0 - 0",
                    "ft_score": "1 - 0",
                    "et_score": "",
                    "ps_score": ""
                }
            }
        ]
    }
}

Name	Type	Example	Description
added	string	2023-12-18 07:45:06	The date and time when the match entered our live score api feed.
away	object	{}	An object carrying details about the away team in the match. It follows the structure of our standard team object.
competition	object	{}	An object carrying details about the competition the match is being played in. It follows the structure of our standard competition object.
country	object	{}	An object carrying details about the country where the match is being played. It follows the structure of our standard country object. Should the match belong to an international competition such as the UEFA Champions League, the value of `country` will be `null`.
date	date	2018-05-15	The date the match began, in UTC.
federation	object	{}	An object carrying details about the federation the match is being played under. It follows the structure of our standard federation object. Should the match belong to a national competition like the English Premier League, the value of `federation` will be `null`.
fixture_id	number	1657338	The `fixture_id` the match belongs to. It could be empty, `0`, or `null`, meaning no fixture was added before the match kicked off.
group_id	number	3353	The `group_id` the match belongs to. This is the same group id used by the competition standings API endpoint and the group standings API endpoint. The list of groups in a competition can be pulled from the dedicated API endpoint.
home	object	{}	An object carrying details about the home team in the match. It follows the structure of our standard team object.
id	number	483252	The `d`, which is NOT the `fixture_id`.
last_changed	datetime	2023-12-18 08:42:53	The date and time in UTC when the match data was last refreshed. While the match unfolds, this value shifts frequently. Once the match reaches `FINISHED` status or `HALF TIME BREAK` status, it changes less often, since no match is underway.
location	string	Campbelltown Stadium	The venue where the match unfolds. It may be the stadium name, the city name, both, or it could even include the country name.
odds	object	{}	An object holding details about pre match and live match betting odds. It follows the structure of a standard odds object.
outcomes	object	{}	An object holding details about the betting outcomes (`1, X, 2`) across the different match periods. It follows the structure of a standard outcomes object.
round	string	QF	The round of the competition in which the match took place. It may be a number such as 1, 2, or 3, or an abbreviation for the knockout stages: R16, QF, SF, F.
scheduled	string	08:00	The hour and minute at which the match was scheduled to begin, in UTC.
scores	object	{}	An object holding details about the score lines at the close of the different match periods. It follows the structure of a standard scores object.
status	string	IN PLAY	The status of the match: `FINISHED`.
time	string	43	The time value.

The time value can be one of these 3 options:

Value	Meaning
`FT`	Means the 90 minutes have finished
`AET`	Means the 120 minutes have finished
`AP`	Means the penalty shootout has finished.

EXAMPLES

The examples below demonstrate how to call this endpoint across several programming languages, with a competition_id passed in as a filter. cUrl:

curl -XGET "https://api.football-api.com/matches/history.json?key=demo_key&secret=demo_secret&competition_id=4"

PHP:

file_get_contents('https://api.football-api.com/history/live.json?key=demo_key\&secret=demo_secret\&competition_id=4');

Python:

import urllib2
req = urllib2.Request('https://api.football-api.com/matches/history.json?key=demo_key\&secret=demo_secret\&competition_id=4')
response = urllib2.urlopen(req)
print response.read()

Match History

ENDPOINT

PARAMETERS

RESPONSE

EXAMPLES

Didn't find what you need?