Matches - AnySport

The core match-query endpoint, supporting free combinations of filters such as a single date, a date range, league+season, team, or a single match_id. It returns basic match information, with the score included for completed matches. Most “fixtures/results/calendar” pages use this endpoint as their data source; if you only need to query a relative time window like “the next week,” using Recent Matches is more convenient (it saves you from calculating dates yourself). Once you have a match_id, you can use it with endpoints like Match Details, Lineups, Live Score, and Live Match Stats to dig deeper into a specific match.

Endpoint

GET /v1/soccer/matches

Parameters

Filter conditions can be combined; season is required when league_id is provided without a date/single-match constraint, and optional otherwise.

Parameter	Type	Required	Description
`match_id`	string	No	Match ID (`as_`)
`date`	string	No	Single day, `YYYY-MM-DD` (UTC)
`from` / `to`	string	No	Date range, `YYYY-MM-DDTHH:mm`example: `from=2026-08-16T20:00&to=2026-08-17T02:00`
`league_id`	string	No	League (`asl_`)
`team_id`	string	No	Team (`ast_`)
`season`	string	Conditionally required	Required when `league_id` is provided without any date (date/from/to) or match_id (including the league+team combination); can be omitted when a date or single match is already specified
`status`	string	No	Status filter (e.g. `FT`, `AET`, `Not Started`, `Cancl.`). For in-progress/not-yet-started matches, `status` takes the form of a plain numeric minute or `HH:MM`, which varies per value — this parameter is not suitable for filtering “in progress/not started”; use a date range plus client-side interpretation instead
`lang`	string	No	`en` / `zh-CN`; invalid values silently fall back to the default language — see `GET /languages` (19) for available values
`page` / `limit`	int	No	Pagination, limit range 1–100

Providing league_id without season, and without a date/single-match constraint, returns 400.

Response fields (data: array)

Field	Type	Description
`match_id`	string	Match ID (`as_` prefix, consistent across all endpoints)
`date`	string	Kickoff date `YYYY-MM-DD` (UTC, ISO, matches the input format)
`time`	string	Kickoff time `HH:mm` (UTC)
`status`	string	Textual status (`FT`/`AET`/`Not Started`…) / `HH:MM` kickoff time / plain numeric minute, may be an empty string
`status_label`	string	Localized text for the match status (returned per `lang`, e.g. for `lang=zh-CN` it would be `完场`); the original `status` value is unchanged; sent when `lang` is a non-default language and a localized text exists for that textual status — not every value has localized text, and when there is no corresponding text this field is omitted, so clients must handle that gracefully (`HH:MM`/plain numeric minute forms never have a label)
`league` / `league_id`	string	League name / ID
`season`	string	Season
`home` / `away`	object	`{ name, team_id }`
`ht_score`	string	Half-time score (returned for completed matches; normalized to the `1-0` form, no spaces)
`ft_score`	string	Regular 90-minute score (returned for completed matches)
`et_score`	string	Cumulative score at the end of extra time (e.g. `3-1`; returned only for matches that went to extra time, using the same convention as the live livescore feed)
`penalty_score`	string	Penalty shootout score (returned only for matches decided by penalties)
`venue`	string	Venue (may be empty)

*_label convention: when lang is a non-default language, status retains its original value, and a parallel localized label status_label is added (only textual statuses can be localized; when no corresponding localized text exists, this field is omitted, so clients must handle that gracefully); team names/league names (home/away/league) are not yet localized by lang.

For matches decided by a penalty shootout (status=Pen.), ft_score may include a nominal 1-goal credit for the winning side of the shootout, and et_score is the net score for the extra-time period; use penalty_score to determine the outcome.

Enum reference

The status string takes one of three forms: 1). Textual status (categorized as follows):

Value	Meaning
`Not Started`	Not started: not yet begun
`TBA`	Not started: time to be announced
“ (empty string)	Not started: unscheduled/unmarked, treated as not started
`HT`	In progress: half-time break
`ET`	In progress: extra time in progress
`P`	In progress: penalty shootout in progress
`Break Time`	In progress: break between extra-time halves, or between extra time and the penalty shootout
`FT`	Finished: end of regulation time (Full Time, most common)
`AET`	Finished: ended after extra time (After Extra Time)
`Pen.`	Finished: decided by penalty shootout (Penalties)
`Awarded`	Finished: awarded loss/win (technical loss — forfeiture, eligibility issues, or other administrative rulings)
`WO`	Finished: forfeit/win by default (Walkover)
`Postp.`	Postponed: postponed
`Delayed`	Postponed: kickoff delayed
`Cancl.` / `Cancelled`	Cancelled: cancelled
`Abandoned` / `Aban.`	Interrupted: match abandoned
`Susp.`	Interrupted: suspended (interrupted after kickoff)
`Int.`	Interrupted: interrupted

2). HH:MM form (e.g. 15:00, 19:45): not started, the value is the UTC kickoff time (matches the time field). 3). Plain numeric form (e.g. 9, 45, 88): in progress, the value is the current match minute.

Request examples

# Query fixtures by league+season
GET /v1/soccer/matches?league_id=asl_62db9cfc3ebf4b87a44570b16668b23e&season=2026&limit=5&lang=en

# Query by date+league+season, filtered by status value (status=AET)
GET /v1/soccer/matches?date=2026-07-12&league_id=asl_62db9cfc3ebf4b87a44570b16668b23e&season=2026&status=AET&limit=5

Response examples

league+season (HTTP 200, excerpt)

{
  "success": true,
  "data": [
    {
      "match_id": "as_37f0da0520bb4e9a9588f80994cefc5b",
      "date": "2026-07-15",
      "time": "19:00",
      "status": "19:00",
      "league": "World Cup",
      "league_id": "asl_62db9cfc3ebf4b87a44570b16668b23e",
      "season": "2026",
      "home": {
        "name": "England",
        "team_id": "ast_13e4e7eccd7640de91c13cffcf0c3ff2"
      },
      "away": {
        "name": "Argentina",
        "team_id": "ast_9137ee449e3b40a68149ca319373adaf"
      },
      "venue": ""
    },
    {
      "match_id": "as_e59479b08f194c1b91df261d9ca56878",
      "date": "2026-07-14",
      "time": "19:00",
      "status": "19:00",
      "league": "World Cup",
      "league_id": "asl_62db9cfc3ebf4b87a44570b16668b23e",
      "season": "2026",
      "home": {
        "name": "France",
        "team_id": "ast_99cc49049ab642909e034538476c64ee"
      },
      "away": {
        "name": "Spain",
        "team_id": "ast_ac0fd01a74b04b61ac8e7b0d8a774cb2"
      },
      "venue": ""
    }
  ],
  "meta": {
    "total": 102,
    "page": 1,
    "limit": 5,
    "total_pages": 21,
    "timestamp": "2026-07-13T19:18:24.076830600Z"
  },
  "traceId": "f11f21f6-0b68-438d-94b7-c8622470176f"
}

HTTP 200

{
  "success": true,
  "data": [
    {
      "match_id": "as_3b37c382f39a4235aa93705f053b2da4",
      "date": "2026-07-12",
      "time": "01:00",
      "status": "AET",
      "league": "World Cup",
      "league_id": "asl_62db9cfc3ebf4b87a44570b16668b23e",
      "season": "2026",
      "home": {
        "name": "Argentina",
        "team_id": "ast_9137ee449e3b40a68149ca319373adaf"
      },
      "away": {
        "name": "Switzerland",
        "team_id": "ast_499130f3976546089056d8d747b6c059"
      },
      "ht_score": "1-0",
      "ft_score": "1-1",
      "et_score": "3-1",
      "venue": ""
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 5,
    "total_pages": 1,
    "timestamp": "2026-07-13T19:18:24.266517800Z"
  },
  "traceId": "bd249d3c-6058-49de-a23f-a12d6b0ea65a"
}

Error examples

All return HTTP 400, error.code INVALID_PARAMS.

# league without season
GET /v1/soccer/matches?league_id=asl_62db9cfc3ebf4b87a44570b16668b23e&limit=5

# league+team without season
GET /v1/soccer/matches?league_id=asl_62db9cfc3ebf4b87a44570b16668b23e&team_id=ast_9137ee449e3b40a68149ca319373adaf&limit=5

​Endpoint

​Parameters

​Response fields (data: array)

​Enum reference

​Request examples

​Response examples

​Error examples

Endpoint

Parameters

Response fields (data: array)

Enum reference

Request examples

Response examples

Error examples