---
id: api-events
title: events Method — Match List
description: Reference for the EVENTS method, which returns matches for a selected sport, country, or tournament.
version: v1
language: en
---

# `events` Method — Match List

## Purpose

The `events` method returns matches for a selected sport. You can optionally limit the
list to one tournament.

The response contains:

- tournament information;
- main match data;
- teams or participants;
- start time;
- current score and period for Live;
- a short set of betting markets and odds;
- available Live statistics, video, and tracker ID.

Use the `event` method to retrieve the complete betting market list for one match.

All fields are documented separately in the
[Sport Line API Field Reference](../data-models/field-reference.md).

## Before Making the Request

The request requires `sportId`. Retrieve it through [`menu`](menu.md) or
[`sports`](optional-methods/sports.md).

To request matches from a specific tournament, you also need `tournamentId`. Retrieve
it from `menu` or [`tournaments`](optional-methods/tournaments.md).

Do not use stored static `sportId` and `tournamentId` values without checking the
current navigation. These IDs must be present in the current `menu`, or obtained through
the `sports → countries → tournaments` sequence for the same `live` or `line` type.

The API shows only sections that currently contain matches. If the only match in a
tournament ends or disappears, the tournament will be absent from the next navigation
response. If that was the sport's only match, the sport itself will disappear as well.

Even when using `tournamentId=0`, take `sportId` from a current API response.

## Request

```http
GET https://YOUR_API_DOMAIN/v1/events/{sportId}/{tournamentId}/{format}/{count}/{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 |
| `tournamentId` | number | yes | Tournament ID. Pass `0` to retrieve matches from all available tournaments of the selected sport |
| `format` | string | yes | `events` supports only `sub`, which groups matches by tournament |
| `count` | number | yes | Originally controlled the amount of returned data. This limit has been removed: pass `50`, and the API will return all available matches in the selected scope |
| `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 | Matches returned |
|---|---|
| `live` | Matches currently in progress |
| `line` | Upcoming Prematch matches |

### The `format` Parameter

The match list supports only the `sub` format. It groups matches by tournament:

```text
body
└── tournament
    └── events_list
        └── matches
```

### The `count` Parameter

The parameter was created to limit the amount of returned data, but the limit was later
removed. The segment remains a required part of the URL for compatibility.

Always pass `50`. Regardless of this value, the API returns all available matches for
the selected sport or tournament. Do not use the parameter for pagination or response
size limits.

### Optional Query Parameter

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

Example:

```http
GET https://YOUR_API_DOMAIN/v1/events/{sportId}/0/sub/50/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 requests all Live football matches from all available tournaments:

```bash
curl --request GET \
  --url 'https://YOUR_API_DOMAIN/v1/events/1/0/sub/50/live/en' \
  --header 'Package: YOUR_API_KEY'
```

## Prematch Request Example

This example requests all Prematch football matches from all available tournaments:

```bash
curl --request GET \
  --url 'https://YOUR_API_DOMAIN/v1/events/1/0/sub/50/line/en' \
  --header 'Package: YOUR_API_KEY'
```

To retrieve matches from only one tournament, replace `0` with its `tournamentId`:

```bash
curl --request GET \
  --url 'https://YOUR_API_DOMAIN/v1/events/1/1205475/sub/50/live/en' \
  --header 'Package: YOUR_API_KEY'
```

## Shortened Live Response Example

The following excerpt comes from a real English response. It contains one match, one
betting market, three selections, and one statistics row.

```json
{
  "status": 1,
  "page": "/v1/events",
  "body": [
    {
      "tournament_id": 1205475,
      "tournament_name": "Australia. NPL Northern Territory",
      "events_list": [
        {
          "sgame_id": "0",
          "stat_id": "0",
          "game_id": 746037229,
          "game_start": 1787310000,
          "country_id": 4,
          "country_name": "Australia",
          "tournament_id": 1205475,
          "tournament_name": "Australia. NPL Northern Territory",
          "opp_1_name": "Garuda Darwin",
          "opp_2_name": "Darwin Olympic",
          "game_oc_counter": 134,
          "game_oc_list": [
            {
              "group_id": 1,
              "group_name": "1X2",
              "columns": 3,
              "oc_list": [
                {
                  "oc_group_name": "1X2",
                  "oc_name": "W2",
                  "oc_rate": 1.064,
                  "oc_size": 0,
                  "oc_pointer": "746037229|1|3|0",
                  "oc_block": false,
                  "op_id": null
                },
                {
                  "oc_group_name": "1X2",
                  "oc_name": "X",
                  "oc_rate": 10.0,
                  "oc_size": 0,
                  "oc_pointer": "746037229|1|2|0",
                  "oc_block": false,
                  "op_id": null
                },
                {
                  "oc_group_name": "1X2",
                  "oc_name": "W1",
                  "oc_rate": 27.0,
                  "oc_size": 0,
                  "oc_pointer": "746037229|1|1|0",
                  "oc_block": false,
                  "op_id": null
                }
              ]
            }
          ],
          "sport_id": 1,
          "sport_name": "Football",
          "timer": 4617,
          "score_full": "0:1",
          "score_period": "0:1;0:0",
          "stat_list": [
            {
              "id": 45,
              "name": "Attacks",
              "opp1": "62",
              "opp2": "58"
            }
          ],
          "period_name": "2nd half",
          "vi": "DR_2_1783062440",
          "zp": 746037229
        }
      ]
    }
  ]
}
```

This is a shortened excerpt, not a complete match object. Full responses are linked at
the end of this document.

## Response Structure

### Top-level Fields

| Field | Type | Description |
|---|---|---|
| `status` | number | Request status. A successful response returns `1` |
| `page` | string | Method name. `events` returns `/v1/events` |
| `body` | array | Tournaments containing matches |

### Tournament Object

| Field | Type | Description |
|---|---|---|
| `tournament_id` | number | Tournament ID |
| `tournament_name` | string | Tournament name in the selected language |
| `events_list` | array | Matches in this tournament |

## Main Match Fields

| Field | Type | Description |
|---|---|---|
| `game_id` | number | Match ID. Used to request the detailed `event` method |
| `sgame_id` | string | Reserved test field for match, team, and player statistics. It is not currently used by the API |
| `stat_id` | string | Reserved test field for detailed statistics. It is not currently used by the API |
| `game_mid` | number or `null` | Main match ID. A submatch has its own `game_id`, while `game_mid` points to the main match |
| `game_num` | number | Legacy unused field scheduled for removal from the API |
| `game_start` | number | Match start time as a Unix timestamp in seconds |
| `sport_id` | number | Sport ID |
| `sport_name` | string | Sport name |
| `country_id` | number | Country ID |
| `country_name` | string | Country name |
| `tournament_id` | number | Tournament ID |
| `tournament_name` | string | Tournament name |
| `game_dop_name` | string | Submatch type name, such as `Corners`, `Yellow Cards`, or `1st Half` |
| `game_desk` | string | Game segment type, such as `Half`, `Set`, or `Quarter` |

A Prematch match's `game_id` is not retained when it moves to Live. A new `game_id` is
generated for Live, so do not link Prematch and Live matches by this field.

Do not treat `sgame_id`, `stat_id`, `game_num`, `stat_list_extra`, or `game_plan` as
required integration fields. They are legacy, test, or reserved fields. `game_num` is
scheduled for removal from the API.

## Teams or Participants

| Field | Type | Description |
|---|---|---|
| `opp_1_name` | string | First team or participant name |
| `opp_2_name` | string | Second team or participant name |
| `opp_1_id` | number | Primary ID of the first team or participant |
| `opp_2_id` | number | Primary ID of the second team or participant |
| `opp_1_ids` | array of number | Participant IDs for the first side when it contains multiple players or teams |
| `opp_2_ids` | array of number | Participant IDs for the second side when it contains multiple players or teams |
| `opp_1_icon` | string | Icon file name for the first team or participant |
| `opp_2_icon` | string | Icon file name for the second team or participant |

The `opp_1_ids` and `opp_2_ids` arrays are used when one side of a match contains
multiple participants. Examples include a tennis doubles team or a group match with
several players or teams on each side.

### Ready-to-use Team and Participant Icons

Use the standard SportAPI icons for teams and participants:

```text
https://cdn.sportapi.net/opp/v1/color/{iconName}.webp
```

Take `iconName` from `opp_1_icon` or `opp_2_icon`. In real responses, the name may
include a `.png` extension. Remove the original extension before creating the CDN URL,
then add `.webp` through the URL template.

For example:

```text
opp_1_icon: 8bd073a686a067e6732d8d1688a517c0.png
iconName:    8bd073a686a067e6732d8d1688a517c0
```

Complete URL:

[https://cdn.sportapi.net/opp/v1/color/8bd073a686a067e6732d8d1688a517c0.webp](https://cdn.sportapi.net/opp/v1/color/8bd073a686a067e6732d8d1688a517c0.webp)

Apply the same rule to `opp_2_icon`.

## Score, Period, and Live Data

| Field | Type | Description |
|---|---|---|
| `timer` | number | Current match timer in seconds. Divide by `60` to obtain minutes. Usually `0` in Prematch |
| `score_full` | string | Current overall score |
| `score_period` | string | Current period score. May be an empty string |
| `score_extra` | string | Tennis game score, such as `0:15`. Primarily used in tennis and may appear in related formats, including virtual tennis |
| `period_name` | string | Current period name. Usually an empty string in Prematch |
| `extra_time` | string | Added minutes, for example `+10` |
| `finale` | boolean or `null` | Indicates that the match has ended. Not available for every match |
| `pitch` | string | ID of the participant serving in applicable sports. May be an empty string |
| `stat_list` | array | Current match statistics |
| `stat_list_extra` | array | Reserved test field for additional match descriptions. It is not currently used |
| `sub_games` | array | Not used by `events` and returned as `[]`. The submatch list is available only in a specific `event` response |
| `event_plan` | array | Not used by `events` and returned as `[]`. The component match list is available only in a specific `event` response |
| `game_plan` | any JSON value or `null` | Reserved test field for match descriptions, such as a tournament stage or court type. It is not currently used |

In Prematch, many Live fields contain default values such as `0`, an empty string, an
empty array, or `null`. The client must handle all of these variants correctly.

### Object in `stat_list`

| Field | Type | Description |
|---|---|---|
| `id` | number | Statistic ID |
| `name` | string | Statistic name |
| `opp1` | string | Value for the first team or participant |
| `opp2` | string | Value for the second team or participant |

### Object in `sub_games`

| Field | Type | Description |
|---|---|---|
| `game_id` | number or `null` | Sub-event ID |
| `game_num` | number or `null` | Sub-event number |
| `game_name` | string or `null` | Sub-event name |

`sub_games` refers to separate submatch types such as corners, cards, fouls, first half
only, player statistics, and other available options.

In the `events` match list, the field is returned as an empty array:

```json
"sub_games": []
```

The `events` method does not use `sub_games`; the field is returned only as `[]`. The
submatch list is available when requesting a specific match through `event`. Each item
contains a submatch ID but not its odds. To retrieve the odds, make a separate `event`
request using the selected submatch's `game_id`.

The `events` method does not use `event_plan`; the field is returned as `[]` in match
lists. A populated component match list is available only when requesting a specific
match through `event`.

## Betting Markets and Odds

| Match field | Type | Description |
|---|---|---|
| `game_oc_counter` | number | Total count of available bets or selections for the match |
| `game_oc_list` | array | Short list of the main markets and best odds included in the match list |

`game_oc_counter` may be significantly greater than the number of items actually
present in `game_oc_list`. Use `event` to retrieve the full betting market list for a
selected match.

### The Short List Depends on the Sport

Do not assume that `game_oc_list` contains the same markets, names, or number of
selections for every sport.

For example:

- in football, the short list may contain a `1X2` market with the first team to win, a
  draw, and the second team to win;
- in basketball, selections for the first or second team to win are often returned
  instead of `1X2`;
- tennis has no draw selection.

Handle the array dynamically during integration:

1. Do not build the interface only around the `1X2` market.
2. Do not expect a draw selection to be present.
3. Read the actual `group_name`, `columns`, and `oc_list` from the response.
4. Do not rely on the same market and selection order across different sports.
5. To open all available selections, call `event` using the selected match's `game_id`.

### Market in `game_oc_list`

| Field | Type | Description |
|---|---|---|
| `group_id` | number | Betting market ID |
| `group_name` | string | Market name |
| `columns` | number | Recommended number of display columns |
| `oc_list` | array | Selections and odds in the market |

### Selection in `oc_list`

| Field | Type | Description |
|---|---|---|
| `oc_group_name` | string | Betting market name |
| `oc_name` | string | Selection name |
| `oc_rate` | number | Current odds value |
| `oc_size` | string or number | Handicap, total, or another parameter value. Both types occur in real responses |
| [`oc_pointer`](https://sportapi.net/docs/coupon/bet-placement/bet-pointer.html) | string | Unique bet or selection code. Used to pass the selected bet to the separate bet placement and settlement system |
| `oc_block` | boolean | `true` — the selection is blocked and unavailable; `false` — it is available |
| `op_id` | number or `null` | Player or participant ID for player-specific bets, when applicable |

Odds and `oc_block` may change with every response update.

## Video and Live 3D Tracker

| Field | Type | Description |
|---|---|---|
| `vi` | string or `null` | Live video stream ID. `null` means no ID was provided |
| `zp` | number or `null` | Live 3D Tracker ID. Pass this value to the tracker as `gameid` |
| `va` | number or `null` | `1` — video is available; `null` — no video is available. The value `0` is not used |

If `zp` is `null`, Live 3D Tracker is unavailable for the match. The tracker works only
for Live matches and supported sports.

More information:

- [Live 3D Tracker in Sport Line API](../additional-services/live-3d-tracker.md);
- [Video Streaming in Sport Line API](../additional-services/video-streaming.md);
- [complete Live 3D Tracker integration guide](https://sportapi.net/docs/live-3d-tracker/service-overview.html).

## Live and Prematch Differences

The match object has the same structure, but its fields are populated differently:

- Live updates the timer, score, period, and statistics;
- in Prematch, these fields usually contain initial or empty values;
- `vi` and `zp` relate to additional Live features and may be `null`;
- odds and selection blocking update independently in Live and Prematch;
- when a match moves from Prematch to Live, it receives a new `game_id`.

Request and store Live and Prematch separately.

## Snapshot of Saved Responses

The Live and Prematch examples use football (`sportId=1`) and `tournamentId=0`, so each
file contains all matches from all available football tournaments. The format is `sub`,
and the technical `count` value is `50`.

| Line type | Tournaments in response | Matches in response |
|---|---:|---:|
| Live | 33 | 39 |
| Prematch (`line`) | 427 | 2638 |

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

Full unabridged responses:

- [Live, Russian](../examples/json-responses/events.sport-1.tournament-0.sub-50.live.ru.json)
- [Prematch, Russian](../examples/json-responses/events.sport-1.tournament-0.sub-50.line.ru.json)
- [Live, English](../examples/json-responses/events.sport-1.tournament-0.sub-50.live.en.json)
- [Prematch, English](../examples/json-responses/events.sport-1.tournament-0.sub-50.line.en.json)

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

## Update Frequency

Recommended request frequency for `events`:

- Live — no more than once every 7 seconds;
- Prematch (`line`) — no more than once every 30 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).
