Matches
List matches with comprehensive filters. Fetch match details, events, stats, and lineups — each as separate endpoints.
List matches
GET/api/public/v1/matches
Query parameters
| Parameter | Type | Description |
|---|---|---|
| date optional | string | Filter to a single date (YYYY-MM-DD). |
| from optional | string | Start of date range (YYYY-MM-DD). |
| to optional | string | End of date range (YYYY-MM-DD). |
| status optional | string | Filter by status: scheduled, live, completed. |
| competition_id optional | string | Competition public ID (e.g. season_UCUznkuK). |
| team_id optional | string | Team public ID — returns matches where this team plays. |
| page / per_page optional | integer | Pagination. Default: page=1, per_page=20, max=100. |
http
GET /api/public/v1/matches?per_page=5 Authorization: Bearer sk_live_xxxxxxxxxxxxx # Filter by date GET /api/public/v1/matches?date=2026-06-15 # Filter by date range GET /api/public/v1/matches?from=2026-06-11&to=2026-06-20 # Filter by status GET /api/public/v1/matches?status=live # Filter by team GET /api/public/v1/matches?team_id=team_Nb8itbVl # Filter by competition GET /api/public/v1/matches?competition_id=season_UCUznkuK
json
{
"data": [
{
"id": "match_8f3k2a",
"match_number": 1,
"competition": {
"id": "season_UCUznkuK",
"name": "FIFA World Cup 2026",
"year": 2026
},
"stage": { "name": "Group Stage" },
"group": { "name": "Group A" },
"home_team": { "id": "team_Nb8itbVl", "name": "Mexico", "code": "MEX" },
"away_team": { "id": "team_4SetK8JF", "name": "United States", "code": "USA" },
"status": "scheduled",
"home_score": 0,
"away_score": 0,
"scheduled_at": "2026-06-11T20:00:00.000Z",
"venue": { "name": "Estadio Azteca", "city": "Mexico City" }
}
],
"meta": { "page": 1, "per_page": 5, "total": 104 }
}Get match detail
GET/api/public/v1/matches/:id
Returns full match details including score breakdown by half/extra time.
http
GET /api/public/v1/matches/match_8f3k2a Authorization: Bearer sk_live_xxxxxxxxxxxxx
json
{
"data": {
"id": "match_8f3k2a",
"match_number": 1,
"home_team": { "id": "team_Nb8itbVl", "name": "Mexico", "code": "MEX" },
"away_team": { "id": "team_4SetK8JF", "name": "United States", "code": "USA" },
"status": "completed",
"home_score": 2,
"away_score": 0,
"first_half": { "home": 1, "away": 0 },
"second_half": { "home": 1, "away": 0 },
"extra_time": null,
"home_penalty": null,
"away_penalty": null,
"has_extra_time": false,
"has_penalties": false,
"home_formation": "4-3-3",
"away_formation": "4-2-3-1",
"venue": { "name": "Estadio Azteca", "city": "Mexico City" },
"scheduled_at": "2026-06-11T20:00:00.000Z"
}
}Get match events
GET/api/public/v1/matches/:id/events
Returns goals, cards, substitutions, and other events ordered by minute. Costs 2 units. Requires match_events permission.
http
GET /api/public/v1/matches/match_8f3k2a/events Authorization: Bearer sk_live_xxxxxxxxxxxxx
json
{
"data": [
{
"id": 1,
"type": "goal",
"detail": "normal",
"minute": 23,
"extra_minute": null,
"team": { "id": "team_Nb8itbVl", "name": "Mexico", "code": "MEX" },
"player": { "id": "player_x2f", "name": "R. Jiménez", "position": "Forward" },
"score": { "home": 1, "away": 0 }
},
{
"id": 2,
"type": "card",
"detail": "yellow",
"minute": 67,
"team": { "id": "team_4SetK8JF", "name": "United States", "code": "USA" },
"player": { "id": "player_k3m", "name": "T. Adams", "position": "Midfielder" }
}
]
}Get match stats
GET/api/public/v1/matches/:id/stats
Returns team-level statistics (possession, shots, corners, fouls, etc). Costs 2 units. Requires match_stats permission.
Get match lineups
GET/api/public/v1/matches/:id/lineups
Returns starting XI and substitutes with positions and jersey numbers. Costs 3 units. Requires match_lineups permission.
Live matches
GET/api/public/v1/matches/live
Returns all currently live matches. Costs 2 units. Requires live_matches permission (Starter+ plans).
ℹ️
Match status values: scheduled, in_play, completed. Live endpoint has 15s cache TTL; finished matches are cached for 24h.