---
id: api-tournaments
title: tournaments Method — Tournament and Competition List
description: Reference for the TOURNAMENTS method, which returns tournaments for a selected sport and country.
version: v1
language: en
---

# `tournaments` Method — Tournament and Competition List

## Recommendation: Use `menu` in Most Cases

The `tournaments` method returns tournaments for only one sport and one country. The
same tournaments are already available inside the [`menu`](../menu.md) response.

For a standard integration, `menu` is recommended because one request returns the
complete hierarchy:

```text
sport → country → tournament
```

Step-by-step loading requires separate requests:

```text
1. sports → retrieve sportId
2. countries → retrieve countryId
3. tournaments → retrieve tournamentId
4. events → retrieve tournament matches
```

The `tournaments` method is an additional method. Use it when tournaments should be
loaded only after a sport and country are selected. If the project needs the complete
sports hierarchy immediately, use `menu`.

## Request

```http
GET https://YOUR_API_DOMAIN/v1/tournaments/{sportId}/{countryId}/{type}/{lang}
```

Send the API key in the HTTP header:

```http
Package: YOUR_API_KEY
```

### Path Parameters

| Parameter | Type | Required | Description |
|---|---|---:|---|
| `sportId` | number | yes | Sport ID obtained from `sports` or `menu` |
| `countryId` | number | yes | Country ID obtained from `countries` or `menu` |
| `type` | string | yes | Sports line type: `live` or `line` |
| `lang` | string | yes | Language of names. It must be supported by the API and included in the client's subscription |

Values of `type`:

| Value | Data returned |
|---|---|
| `live` | Tournaments with available Live matches |
| `line` | Tournaments with available Prematch matches |

### Optional Query Parameter

| Parameter | Type | Default | Description |
|---|---|---|---|
| `cybersport` | boolean | `false` | Switches the method to esports tournaments |

Example request for esports data:

```http
GET https://YOUR_API_DOMAIN/v1/tournaments/{sportId}/{countryId}/live/en?cybersport=true
```

The full responses stored with this documentation were retrieved without query
parameters, which means `cybersport=false`.

## Live Request Example

This example uses football (`sportId=1`) and Australia (`countryId=4`):

```bash
curl --request GET \
  --url 'https://YOUR_API_DOMAIN/v1/tournaments/1/4/live/en' \
  --header 'Package: YOUR_API_KEY'
```

## Prematch Request Example

```bash
curl --request GET \
  --url 'https://YOUR_API_DOMAIN/v1/tournaments/1/4/line/en' \
  --header 'Package: YOUR_API_KEY'
```

## Shortened Live Response Example

The following real tournament objects were present under Australia in the saved English
Live `menu` response. Tournament objects in `menu` and `tournaments` use the same fields.

```json
{
  "status": 1,
  "page": "/v1/tournaments",
  "body": [
    {
      "id": 1205475,
      "name": "Australia. NPL Northern Territory",
      "counter": 1,
      "sport_id": 1,
      "countryId": 4
    },
    {
      "id": 1025049,
      "name": "Australia. South Australia. State League",
      "counter": 1,
      "sport_id": 1,
      "countryId": 4
    },
    {
      "id": 1195579,
      "name": "Australia. FFSA State League. Division 2",
      "counter": 1,
      "sport_id": 1,
      "countryId": 4
    }
  ]
}
```

## Shortened Prematch Response Example

These real tournament objects were present under Australia in the saved English
Prematch `menu` response.

```json
{
  "status": 1,
  "page": "/v1/tournaments",
  "body": [
    {
      "id": 149213,
      "name": "Australia Cup",
      "counter": 2,
      "sport_id": 1,
      "countryId": 4
    },
    {
      "id": 2226303,
      "name": "Australia. Queensland Cup. Women",
      "counter": 1,
      "sport_id": 1,
      "countryId": 4
    },
    {
      "id": 1025049,
      "name": "Australia. South Australia. State League",
      "counter": 1,
      "sport_id": 1,
      "countryId": 4
    }
  ]
}
```

The `counter` values represent the sports line only at the time of the response and
change continuously.

## Response Fields

### Top-level Fields

| Field | Type | Description |
|---|---|---|
| `status` | number | Request status. A successful response returns `1` |
| `page` | string | Method name. `tournaments` returns `/v1/tournaments` |
| `body` | array | Available tournaments for the selected sport and country |

### Tournament Object

| Field | Type | Description |
|---|---|---|
| `id` | number | Tournament ID. Used as `tournamentId` in other methods |
| `name` | string | Tournament name in the language specified by `lang` |
| `counter` | number | Number of available matches in this tournament |
| `sport_id` | number | ID of the sport associated with the tournament |
| `countryId` | number | ID of the country associated with the tournament |

Pay attention to the exact JSON field names:

- the sport ID is named `sport_id`;
- the country ID is named `countryId`, with an uppercase `I`.

Do not replace `countryId` with `country_id` when parsing the response.

## Ready-to-use Tournament Icons

Each tournament or competition can use a standard SportAPI icon. Take the `id` value
from the response and insert it in place of `{tournamentId}`:

```text
https://cdn.sportapi.net/tournaments/v1/color/{tournamentId}.webp
```

Example for a tournament with `id: 118737`:

[https://cdn.sportapi.net/tournaments/v1/color/118737.webp](https://cdn.sportapi.net/tournaments/v1/color/118737.webp)

## Relationship with `menu`

Objects in the `tournaments` method's `body` array contain the same fields as tournament
objects inside `menu` for the selected sport and country.

If the methods are called at different times, the tournament list and `counter` values
may differ because the sports line changes continuously.

## Using the Returned `id`

After selecting a tournament, take its `id` field. This identifier is named
`tournamentId` in the match list method's URL.

To request matches for the selected tournament, you need:

- `sportId` from the selected sport;
- `tournamentId` from the selected tournament's `id` field;
- the `live` or `line` type;
- the response language.

When using `menu`, the required `sportId` and `tournamentId` are already available in
one response, so preliminary `sports`, `countries`, and `tournaments` requests are not
required.

Do not request matches using a stored `tournamentId` without checking the current
`tournaments` or `menu` response. A tournament is returned only while it contains
available matches for the selected line type.

If the tournament's only match ends, moves from Prematch to Live, or disappears for
another reason, the tournament will be absent from the corresponding response. Pass to
`events` only a `tournamentId` from the current navigation flow.

## Saved Response Snapshots

The Australia examples above were taken from the saved English `menu` responses for
football (`sportId=1`, `countryId=4`):

| Line type | Tournaments under Australia |
|---|---:|
| Live | 10 |
| Prematch (`line`) | 34 |

These figures describe specific responses retrieved on August 21, 2026. They are not a
permanent description of the API.

The archived direct `tournaments` responses use the original test parameters and are
provided for complete schema verification:

- [Live, Russian](../../examples/json-responses/tournaments.sport-1.country-1.live.ru.json)
- [Prematch, Russian](../../examples/json-responses/tournaments.sport-1.country-1.line.ru.json)
- [Live, English](../../examples/json-responses/tournaments.sport-1.country-1.live.en.json)
- [Prematch, English](../../examples/json-responses/tournaments.sport-1.country-1.line.en.json)

The files contain only API response bodies. No API key is stored in them.

## Update Frequency

Recommended request frequency for `tournaments`:

- Live — no more than once every 60 seconds;
- Prematch (`line`) — no more than once every 120 seconds.

See [Data Update Guidelines](../../getting-started/update-guidelines.md) for more details.

Key, subscription, and parameter errors are documented in
[Error Handling](../../getting-started/error-handling.md).
