Docs menu
SofaScore API endpoint
SofaScore Season Events API
Returns one page (about 30 events) of every fixture or result of a competition season, with the round of each event. The `direction` enum accepts `next` (upcoming fixtures) and `last` (finished results). Follow `has_next_page` to read further pages: a page past the end, a direction with no events (for example `next` in a finished season) and a season id that does not belong to the competition all answer 404. Get `id` from search and `season` from tournament-seasons.
GETapiKey1 credit/requestSofaScoresofascore.seasonEventsResponseDoc
SofaScore/sofascore/season-eventsEndpoint facts
- Method
- GET
- API path
- /sofascore/season-events
- Auth
- apiKey
- Credits
- 1 credit/request
- Charged on
- Successful 2xx responses only
- Platform
- SofaScore
- Response schema
- #/definitions/sofascore.seasonEventsResponseDoc
How this endpoint behaves
Query parameters:
id: required. Numeric SofaScore unique-tournament (competition) id, e.g.17for the Premier League.season: required. Numeric SofaScore season id fromsofascore/tournament-seasons, e.g.96668.direction: required enum. Allowed values:next(upcoming fixtures),last(finished results).page: optional integer. Zero-based page number, about 30 events per page. Defaults to0.
Notable response behavior:
has_next_pageshows whetherpage + 1holds more events; follow it instead of paging until an error.- Upstream answers 404 for a page past the last one, for a direction with no events (for example
nextfor a finished season, orlastbefore a season has started) and for a season id that does not belong to the competition. These cannot be told apart, so all three return 404 with an explanatory message. roundandround_nameare set for competitions that play numbered rounds (leagues) and omitted otherwise (for example the NBA).home_score/away_scoreare omitted for matches that have not started.- Use
sofascore/round-eventsto read a single round, andsofascore/team-eventsfor one team's fixtures.
Example response (shortened):
{
"code": 200,
"msg": "OK",
"data": {
"tournament_id": 17,
"season_id": 96668,
"direction": "last",
"page": 0,
"has_next_page": true,
"count": 1,
"source_url": "https://api.sofascore.com/api/v1/unique-tournament/17/season/96668/events/last/0",
"fetched_at": "2026-10-07T14:00:00Z",
"events": [
{
"id": 16363261,
"slug": "liverpool-fc-ipswich-town",
"start_timestamp": 1788548400,
"start_time": "2026-09-04T19:00:00Z",
"status": { "code": 100, "description": "Ended", "type": "finished" },
"winner_code": 2,
"tournament": { "id": 1, "name": "Premier League", "unique_tournament_id": 17, "unique_tournament_name": "Premier League" },
"home_team": { "id": 32, "name": "Ipswich Town", "short_name": "Ipswich", "slug": "ipswich-town", "country": "England" },
"away_team": { "id": 44, "name": "Liverpool FC", "short_name": "Liverpool", "slug": "liverpool", "country": "England" },
"home_score": { "current": 0 },
"away_score": { "current": 2 },
"round": 3
}
]
}
}
Live monitoring
- Monitored request
- GET /sofascore/season-events?direction=last&id=17&season=96668
- Checks passed, 7 days to 14 Oct 2026
- 100%
- Median response time
- 1.07 s
Sampled response
- Request, 14 Oct 2026
- GET /sofascore/season-events?direction=last&id=17&season=96668
- Items in events
- 30
- Fields filled in every checked item
- 12
| Field | Filled in, of 30 checked | Values in the sample |
|---|---|---|
| id | 30 | |
| slug | 30 | |
| start_timestamp | 30 | 2026-09-12 to 2026-10-12 |
| start_time | 30 | 2026-09-12 to 2026-10-12 |
| status | 30 | |
| winner_code | 30 | |
| tournament | 30 | |
| home_team | 30 | |
| away_team | 30 | |
| home_score | 30 | |
| away_score | 30 | |
| round | 30 | 4 to 6, median 5 |
Request parameters
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| id | string | Yes | Numeric SofaScore unique-tournament (competition) id | 17 | |
| season | string | Yes | Numeric SofaScore season id | 96668 | |
| direction | string | Yes | Upcoming fixtures or finished results Allowed values: next, last. | last | |
| page | integer | No | 0 | Zero-based page number. Defaults to 0 Minimum: 0. | 0 |
| x-api-key (header) | string | Yes | API key required |
cURL example
curl -X GET "https://api.crawlora.net/api/v1/sofascore/season-events?id=17&season=96668&direction=last&page=1" \ -H "x-api-key: $CRAWLORA_API_KEY"
Example JSON response
{
"code": 200,
"msg": "OK",
"data": {
"tournament_id": 17,
"season_id": 96668,
"direction": "last",
"page": 0,
"has_next_page": true,
"count": 1,
"source_url": "https://api.sofascore.com/api/v1/unique-tournament/17/season/96668/events/last/0",
"fetched_at": "2026-10-07T14:00:00Z",
"events": [
{
"id": 16363261,
"slug": "liverpool-fc-ipswich-town",
"start_timestamp": 1788548400,
"start_time": "2026-09-04T19:00:00Z",
"status": {
"code": 100,
"description": "Ended",
"type": "finished"
},
"winner_code": 2,
"tournament": {
"id": 1,
"name": "Premier League",
"unique_tournament_id": 17,
"unique_tournament_name": "Premier League"
},
"home_team": {
"id": 32,
"name": "Ipswich Town",
"short_name": "Ipswich",
"slug": "ipswich-town",
"country": "England"
},
"away_team": {
"id": 44,
"name": "Liverpool FC",
"short_name": "Liverpool",
"slug": "liverpool",
"country": "England"
},
"home_score": {
"current": 0
},
"away_score": {
"current": 2
},
"round": 3
}
]
}
}Request schema
No body schema
Response schema
#/definitions/sofascore.seasonEventsResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | sofascore.SeasonEventsResponse | No | ||||
| data.count | integer | No | ||||
| data.direction | string | No | next | |||
| data.events | array | No | ||||
| data.events[].away_score | object | No | Away side's score, when available. | |||
| data.events[].away_score.current | integer | No | Current score, which is the final score once the match is over. | |||
| data.events[].away_score.period1 | integer | No | Score in the first period. | |||
| data.events[].away_score.period2 | integer | No | Score in the second period. | |||
| data.events[].away_team | object | No | Away side. | |||
| data.events[].away_team.country | string | No | Spain | Country the team belongs to. | ||
| data.events[].away_team.id | integer | No | 2817 | SofaScore team id. Use it with the team endpoints. | ||
| data.events[].away_team.name | string | No | FC Barcelona | Full team name. | ||
| data.events[].away_team.national | boolean | No | True for a national team. | |||
| data.events[].away_team.short_name | string | No | Barcelona | Shortened team name. | ||
| data.events[].away_team.slug | string | No | barcelona | URL slug of the team on SofaScore. | ||
| data.events[].home_score | object | No | Home side's score, when available. | |||
| data.events[].home_score.current | integer | No | Current score, which is the final score once the match is over. | |||
| data.events[].home_score.period1 | integer | No | Score in the first period. | |||
| data.events[].home_score.period2 | integer | No | Score in the second period. | |||
| data.events[].home_team | object | No | Home side. | |||
| data.events[].home_team.country | string | No | Spain | Country the team belongs to. | ||
| data.events[].home_team.id | integer | No | 2817 | SofaScore team id. Use it with the team endpoints. | ||
| data.events[].home_team.name | string | No | FC Barcelona | Full team name. | ||
| data.events[].home_team.national | boolean | No | True for a national team. | |||
| data.events[].home_team.short_name | string | No | Barcelona | Shortened team name. | ||
| data.events[].home_team.slug | string | No | barcelona | URL slug of the team on SofaScore. | ||
| data.events[].id | integer | No | 14025013 | SofaScore event id. Use it with the event endpoints. | ||
| data.events[].round | integer | No | 3 | |||
| data.events[].round_name | string | No | ||||
| data.events[].slug | string | No | URL slug of the match on SofaScore. | |||
| data.events[].start_time | string | No | 2025-08-15T19:00:00Z | Start time in UTC (RFC 3339). | ||
| data.events[].start_timestamp | integer | No | Start time as a Unix timestamp in seconds. | |||
| data.events[].status | object | No | Current status of the match. | |||
| data.events[].status.code | integer | No | SofaScore's numeric status code, for example 0 for not started and 100 for ended. | |||
| data.events[].status.description | string | No | Ended | Status as displayed, for example "Ended". | ||
| data.events[].status.type | string | No | finished | Status group, for example `notstarted`, `inprogress` or `finished`. | ||
| data.events[].tournament | object | No | Tournament and parent competition the match belongs to. | |||
| data.events[].tournament.category | string | No | England | Category the tournament sits under, usually a country or region. | ||
| data.events[].tournament.id | integer | No | SofaScore id of the tournament the match is filed under. The seasons, standings and round endpoints take `unique_tournament_id` instead. | |||
| data.events[].tournament.name | string | No | Premier League | Tournament name. | ||
| data.events[].tournament.slug | string | No | premier-league | URL slug of the tournament on SofaScore. | ||
| data.events[].tournament.unique_tournament_id | integer | No | 17 | Id of the parent competition. This is the tournament id the tournament-seasons, standings and round-events endpoints take. | ||
| data.events[].tournament.unique_tournament_name | string | No | Premier League | Name of the parent competition. | ||
| data.events[].winner_code | integer | No | Result code: 1 when the home side won, 2 when the away side won, 3 for a draw. Omitted until the match is decided. | |||
| data.fetched_at | string | No | ||||
| data.has_next_page | boolean | No | ||||
| data.page | integer | No | ||||
| data.season_id | integer | No | ||||
| data.source_url | string | No | ||||
| data.tournament_id | integer | No | ||||
| msg | string | No | OK |
Failure responses
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 404 | Not Found | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 503 | Service Unavailable | #/definitions/app.Response |
Code examples
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/sofascore/season-events?id=17&season=96668&direction=last&page=1" \
-H "x-api-key: $CRAWLORA_API_KEY"Shared guides
Related
More SofaScore endpoint docsSofaScore APISofaScore categories for a sport API documentationSofaScore competitions in a category API documentationSofaScore league draft picks API documentationSofaScore league draft API documentationSofaScore esports game detail API documentationSofaScore event at-bat pitches API documentation