API docs by Redocly

TheSportsDB API (v2 · measured 5 Oct 2026)

Download OpenAPI specification:

Terms of Service

v2 is for premium keys. It adds full team schedules, whole seasons in one call, TV listings by country, sport or channel, and documented live scores.

GET https://www.thesportsdb.com/api/v2/json/{group}/{name}/{parameter}
X-API-KEY: your-premium-key
  • Keys: sent in the X-API-KEY header. The free keys get HTTP 400.
  • Responses: one JSON object whose key is the endpoint's group: search, lookup, list, filter, all, schedule or livescore. Values are strings or null, except that search/... sends ids as numbers.
  • No results: {"Message":"No data found"}, with HTTP 200.
  • Limits: each endpoint's description gives the documented limit and the records measured on 5 Oct 2026. They differ: several endpoints return more than documented.
  • Times: dateEvent, strTime and strTimestamp are UTC.
  • Not in v2: league tables. Use v1's lookuptable.php with your premium key.

The guides cover these in detail, with recipes for common tasks.

Search

Find records by name.

Search leagues

Records measured 5 Oct 2026: 2.

Documented limit: 10.

Authorizations:
apiKey
path Parameters
name
required
string
Example: English Premier League

League name; spaces as %20.

Responses

Response samples

Content type
application/json
{}

Search teams

Ids are JSON numbers here, strings everywhere else.

Records measured 5 Oct 2026: 12.

Documented limit: 10.

Authorizations:
apiKey
path Parameters
name
required
string
Example: Arsenal

Team name; spaces as %20.

Responses

Response samples

Content type
application/json
{}

Search players

Records measured 5 Oct 2026: 1.

Documented limit: 10.

Authorizations:
apiKey
path Parameters
name
required
string
Example: Danny Welbeck

Player name; spaces as %20.

Responses

Response samples

Content type
application/json
{}

Search events

Needs the exact stored event name; Arsenal vs Chelsea returns No data found (v1 searchevents.php is looser).

Records measured 5 Oct 2026: —.

Documented limit: 10.

Authorizations:
apiKey
path Parameters
name
required
string
Example: Arsenal vs Chelsea

Event name; spaces as %20.

Responses

Response samples

Content type
application/json
Example
{}

Search venues

Records measured 5 Oct 2026: 3.

Documented limit: 10.

Authorizations:
apiKey
path Parameters
name
required
string
Example: Wembley

Venue name; spaces as %20.

Responses

Response samples

Content type
application/json
{}

Lookup

Fetch records by id, and the details attached to a team, player or event.

Look up a league

Records measured 5 Oct 2026: 1.

Documented limit: 1.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 4328

The league id.

Responses

Response samples

Content type
application/json
{
  • "lookup": [
    ]
}

Look up a team

Records measured 5 Oct 2026: 1.

Documented limit: 1.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 133604

The team id.

Responses

Response samples

Content type
application/json
{
  • "lookup": [
    ]
}

A team's kits

Records measured 5 Oct 2026: 18.

Documented limit: 1.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 133597

The team id.

Responses

Response samples

Content type
application/json
{}

Look up a player

Records measured 5 Oct 2026: 1.

Documented limit: 1.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 34145937

The player id.

Responses

Response samples

Content type
application/json
{}

A player's contracts

Records measured 5 Oct 2026: 1.

Documented limit: 1.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 34147178

The player id.

Responses

Response samples

Content type
application/json
{}

A player's results (individual sports)

Records measured 5 Oct 2026: 24.

Documented limit: 1.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 34160573

The player id.

Responses

Response samples

Content type
application/json
{
  • "lookup": [
    ]
}

A player's honours

Records measured 5 Oct 2026: 5.

Documented limit: 1.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 34147178

The player id.

Responses

Response samples

Content type
application/json
{}

A player's milestones

Records measured 5 Oct 2026: 3.

Documented limit: 1.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 34161397

The player id.

Responses

Response samples

Content type
application/json
{}

A player's former teams

Records measured 5 Oct 2026: 6.

Documented limit: 1.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 34147178

The player id.

Responses

Response samples

Content type
application/json
{}

A player's season statistics

Records measured 5 Oct 2026: 315.

Documented limit: 1.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 34146304

The player id.

Responses

Response samples

Content type
application/json
{}

Look up an event

Records measured 5 Oct 2026: 1.

Documented limit: 1.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 441613

The event id.

Responses

Response samples

Content type
application/json
{
  • "lookup": [
    ]
}

An event's lineups

Adds strFormation and strPositionShort (often null) to v1's fields.

Records measured 5 Oct 2026: 22.

Documented limit: 1.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 1032723

The event id.

Responses

Response samples

Content type
application/json
{
  • "lookup": [
    ]
}

An event's results (individual sports)

Records measured 5 Oct 2026: 22.

Documented limit: 1.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 652890

The event id.

Responses

Response samples

Content type
application/json
{
  • "lookup": [
    ]
}

An event's team statistics

Records measured 5 Oct 2026: 16.

Documented limit: 1.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 1032723

The event id.

Responses

Response samples

Content type
application/json
{
  • "lookup": [
    ]
}

An event's timeline

Records measured 5 Oct 2026: 10.

Documented limit: 1.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 1032718

The event id.

Responses

Response samples

Content type
application/json
{
  • "lookup": [
    ]
}

The channels showing an event

Records measured 5 Oct 2026: 13.

Documented limit: 1.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 2494052

The event id.

Responses

Response samples

Content type
application/json
{}

An event's highlight video

The video URL is in strVideo.

Records measured 5 Oct 2026: 1.

Documented limit: 1.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 441613

The event id.

Responses

Response samples

Content type
application/json
{
  • "lookup": [
    ]
}

Look up a venue

Records measured 5 Oct 2026: 1.

Documented limit: 1.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 16163

The venue id.

Responses

Response samples

Content type
application/json
{}

Lists

Lists of leagues, seasons, teams and players.

A league's teams

Badges and colours, but no alternate names: look teams up by id for those.

Records measured 5 Oct 2026: 20.

Documented limit: 100.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 4328

The league id.

Responses

Response samples

Content type
application/json
{}

A league's seasons

With badge, poster and description.

Records measured 5 Oct 2026: 35.

Documented limit: 100.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 4328

The league id.

Responses

Response samples

Content type
application/json
{}

A team's squad

Records measured 5 Oct 2026: 27.

Documented limit: 100.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 133604

The team id.

Responses

Response samples

Content type
application/json
{}

A league's season posters

Every season poster and badge uploaded for the league, with the uploader; several per season are possible. In TheSportsDB's OpenAPI description but not on its HTML documentation page.

Records measured 5 Oct 2026: 9.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 4328

The league id.

Responses

Response samples

Content type
application/json
{}

All

Complete catalogues of countries, sports and leagues.

All countries

Records measured 5 Oct 2026: 256.

Documented limit: 500.

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{}

All sports

Records measured 5 Oct 2026: 37.

Documented limit: 500.

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{}

All leagues

Records measured 5 Oct 2026: 1547.

Documented limit: 3000.

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{
  • "all": [
    ]
}

Schedules

Fixtures and results. Times are UTC.

Next events of a league

Records measured 5 Oct 2026: 20.

Documented limit: 10.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 4328

The league id.

Responses

Response samples

Content type
application/json
{}

Next events of a team

Records measured 5 Oct 2026: 10.

Documented limit: 10.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 133604

The team id.

Responses

Response samples

Content type
application/json
{}

Next events of a venue

Records measured 5 Oct 2026: 3.

Documented limit: 10.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 16163

The venue id.

Responses

Response samples

Content type
application/json
{}

Previous events of a league

Records measured 5 Oct 2026: 20.

Documented limit: 10.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 4328

The league id.

Responses

Response samples

Content type
application/json
{}

Previous events of a team

Records measured 5 Oct 2026: 10.

Documented limit: 10.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 133604

The team id.

Responses

Response samples

Content type
application/json
{}

Previous events of a venue

Records measured 5 Oct 2026: 10.

Documented limit: 10.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 16163

The venue id.

Responses

Response samples

Content type
application/json
{}

A team's full schedule

Past and future, across all competitions.

Records measured 5 Oct 2026: 48.

Documented limit: 250.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 133604

The team id.

Responses

Response samples

Content type
application/json
{}

A league's whole season

Every event of the season in one call.

Records measured 5 Oct 2026: 380.

Documented limit: 3000.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 4328

The league id.

season
required
string
Example: 2026-2027

Season name, from strCurrentSeason.

Responses

Response samples

Content type
application/json
{}

TV

TV listings: which channels show which events.

Every TV listing on a day

Worldwide.

Records measured 5 Oct 2026: 287.

Documented limit: 100.

Authorizations:
apiKey
path Parameters
date
required
string <date>
Example: 2026-10-05

A day, YYYY-MM-DD.

Responses

Response samples

Content type
application/json
{}

A country's TV listings

About a week of listings.

Records measured 5 Oct 2026: 90.

Documented limit: 100.

Authorizations:
apiKey
path Parameters
country
required
string
Example: Canada

Country of the channel.

Responses

Response samples

Content type
application/json
{}

A sport's TV listings

Records measured 5 Oct 2026: 189.

Documented limit: 100.

Authorizations:
apiKey
path Parameters
sport
required
string
Example: Ice Hockey

Sport name; spaces as %20.

Responses

Response samples

Content type
application/json
{}

A channel's TV listings, by name

Records measured 5 Oct 2026: 3.

Documented limit: 100.

Authorizations:
apiKey
path Parameters
channel
required
string
Example: TSN 1

Channel name in TheSportsDB's spelling (TSN 1, not TSN1); partial names match.

Responses

Response samples

Content type
application/json
{}

A channel's TV listings, by id

Records measured 5 Oct 2026: 4.

Documented limit: 100.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 8631

The channel id, idChannel.

Responses

Response samples

Content type
application/json
{}

Live scores

Games in progress.

Games in progress in a sport or a league

A league with nothing in play returns No data found. Entries can be stale; check updated.

Records measured 5 Oct 2026: 17.

Documented limit: 100.

Authorizations:
apiKey
path Parameters
sportOrLeague
required
string
Example: soccer

A sport name (e.g. soccer) or a league id (e.g. 4328).

Responses

Response samples

Content type
application/json
{}

Every game in progress

Records measured 5 Oct 2026: 54.

Documented limit: 500.

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{}