Matches

GET /tournaments/{tournament_id}/matches

Simple Access

Returns the matches of the given tournament using various filters. If the match type is "ffa", this list is limited to the first 4 opponents ordered by their position.

Resource URL

https://api.toornament.com/viewer/v2/tournaments/{tournament_id}/matches

HTTP headers

  • X-Api-Key
    string

    API key of your application (see Authentication)

  • Range
    string

    A range of requested items using the matches unit. The size of the range cannot exceed 128. (see Pagination)

    Example: matches=0-127

Path parameters

  • tournament_id
    string

    The id of the tournament for which matches must be retrieved

Query Parameters

  • stage_ids
    array

    One or several stage ids to filter

    Example: 618965765764577354,618931468547654563

  • stage_numbers
    array

    One or several stage numbers to filter

    Example: 1,3

  • group_ids
    array

    One or several group ids to filter

    Example: 618965314871946714,618932178746476544

  • group_numbers
    array

    One or several group numbers to filter

    Example: 2,4

  • round_ids
    array

    One or several round ids to filter

    Example: 618943519431786343,618965178941654763

  • round_numbers
    array

    One or several round numbers to filter

    Example: 1,2

  • statuses
    array

    One or several match statuses to filter

    Example: pending,running

  • is_scheduled
    boolean

    Whether to include or exclude scheduled matches

    Possible values: 0, 1

  • scheduled_before
    datetime

    A datetime to include all matches scheduled before or at the datetime

    Format: RFC 3339 (combined date, time and utc offset)

    Example: 2015-12-31T00:00:00+00:00

  • scheduled_after
    datetime

    A datetime to include all matches scheduled after or at the datetime

    Format: RFC 3339 (combined date, time and utc offset)

    Example: 2015-12-31T00:00:00+00:00

  • participant_ids
    array

    One or several participant ids involved in the matches to filter

    Example: 618965416546776434,618975467354349191

  • sort
    string

    A method to sort the filtered data. Structure sorting uses the stage, group, round and match numbers. Schedule sorting uses the scheduled date. Latest results sorting uses the date at which the matches were played (not scheduled).

    Possible values: structure, schedule, latest_results

    Default: structure

Request Body

This endpoint doesn't require a request body.

Response

[206] Matches retrieved

Example
[
    {
        "id": "618954615761465416",
        "stage_id": "618983668512789184",
        "group_id": "618985165765456465",
        "round_id": "618965146546456651",
        "number": 2,
        "type": "duel",
        "status": "pending",
        "scheduled_datetime": "2015-12-31T00:00:00+00:00",
        "played_at": "2015-12-31T00:00:00+00:00",
        "opponents": [
            {
                "number": 1,
                "position": 1,
                "result": "win",
                "rank": 3,
                "forfeit": false,
                "score": 15,
                "participant": {
                    "id": "375143143408309123",
                    "name": "Jon Snow",
                    "custom_fields": {
                        "country": "UK",
                        "logo": {
                            "logo_small": "url_to_small_image",
                            "logo_medium": "url_to_medium_image",
                            "logo_large": "url_to_large_image"
                        }
                    }
                }
            }
        ]
    }
]
Structure (collection)
  • id
    string

    The id of the match and the match (they both share the same id).

    Example: "618954615761465416"

  • stage_id
    string

    The id of the stage that contains this match

    Example: "618983668512789184"

  • group_id
    string

    The id of the group that contains this match

    Example: "618985165765456465"

  • round_id
    string

    The id of the round that contains this match

    Example: "618965146546456651"

  • number
    integer

    The match number (a relative identifier within a round)

    Example: 2

  • type
    string

    The type of match

    Possible values: duel, ffa, bye

  • status
    string

    The status of the match

    Possible values: pending, running, completed

  • scheduled_datetime
    datetime|null

    The scheduled date of the match

    Format: RFC 3339 (combined date, time and utc offset)

    Example: "2015-12-31T00:00:00+00:00"

  • played_at
    datetime|null

    The timestamp on which the match was played (a result was provided)

    Format: RFC 3339 (combined date, time and utc offset)

    Example: "2015-12-31T00:00:00+00:00"

  • opponents
    array[object]

    List of match opponents.

GET /tournaments/{tournament_id}/matches/{id}

Simple Access

Returns a match by the given id with games. If the match type is "ffa", games are limited to the first 4 opponents ordered by their position.

Resource URL

https://api.toornament.com/viewer/v2/tournaments/{tournament_id}/matches/{id}

HTTP headers

Path parameters

  • tournament_id
    string

    The id of the tournament for which matches must be retrieved

  • id
    string

    The id of the match to retrieve

Query Parameters

This endpoint doesn't have any query parameters.

Request Body

This endpoint doesn't require a request body.

Response

[200] Match retrieved

Example
{
    "id": "618954615761465416",
    "stage_id": "618983668512789184",
    "group_id": "618985165765456465",
    "round_id": "618965146546456651",
    "number": 2,
    "type": "duel",
    "status": "pending",
    "scheduled_datetime": "2015-12-31T00:00:00+00:00",
    "played_at": "2015-12-31T00:00:00+00:00",
    "opponents": [
        {
            "number": 1,
            "position": 1,
            "result": "win",
            "rank": 3,
            "forfeit": false,
            "score": 15,
            "participant": {
                "id": "375143143408309123",
                "name": "Jon Snow",
                "custom_fields": {
                    "country": "UK",
                    "logo": {
                        "logo_small": "url_to_small_image",
                        "logo_medium": "url_to_medium_image",
                        "logo_large": "url_to_large_image"
                    }
                }
            }
        }
    ],
    "games": [
        {
            "number": 1,
            "status": "pending",
            "opponents": [
                {
                    "number": 1,
                    "position": 1,
                    "result": "win",
                    "rank": 3,
                    "forfeit": false,
                    "score": 15
                }
            ]
        }
    ]
}
Structure (object)
  • id
    string

    The id of the match and the match (they both share the same id).

    Example: "618954615761465416"

  • stage_id
    string

    The id of the stage that contains this match

    Example: "618983668512789184"

  • group_id
    string

    The id of the group that contains this match

    Example: "618985165765456465"

  • round_id
    string

    The id of the round that contains this match

    Example: "618965146546456651"

  • number
    integer

    The match number (a relative identifier within a round)

    Example: 2

  • type
    string

    The type of match

    Possible values: duel, ffa, bye

  • status
    string

    The status of the match

    Possible values: pending, running, completed

  • scheduled_datetime
    datetime|null

    The scheduled date of the match

    Format: RFC 3339 (combined date, time and utc offset)

    Example: "2015-12-31T00:00:00+00:00"

  • played_at
    datetime|null

    The timestamp on which the match was played (a result was provided)

    Format: RFC 3339 (combined date, time and utc offset)

    Example: "2015-12-31T00:00:00+00:00"

  • opponents
    array[object]

    List of match opponents.

  • games
    array[object]

    List of match games.

GET /disciplines/{discipline_id}/matches

Simple Access

Retrieve a collection of matches from a specific discipline, filtered and sorted by the given query parameters. If the match type is "ffa", this list is limited to the first 4 opponents ordered by their position.

Resource URL

https://api.toornament.com/viewer/v2/disciplines/{discipline_id}/matches

HTTP headers

  • X-Api-Key
    string

    API key of your application (see Authentication)

  • Range
    string

    A range of requested items using the matches unit. The size of the range cannot exceed 128. (see Pagination)

    Example: matches=0-127

Path parameters

  • discipline_id
    string

    The string id of the discipline

Query Parameters

  • is_featured
    boolean

    Whether to include or exclude featured tournaments

    Possible values: 0, 1

  • statuses
    array

    One or several match statuses to filter

    Example: pending,running

  • scheduled_before
    datetime

    A datetime to include all matches scheduled before or at the datetime

    Format: RFC 3339 (combined date, time and utc offset)

    Example: 2015-12-31T00:00:00+00:00

  • scheduled_after
    datetime

    A datetime to include all matches scheduled after or at the datetime

    Format: RFC 3339 (combined date, time and utc offset)

    Example: 2015-12-31T00:00:00+00:00

  • participant_ids
    array

    One or several participant ids involved in the matches to filter

    Example: 618965416546776434,618975467354349191

  • tournament_ids
    array

    One or several tournament ids owned in the matches to filter

    Example: 378426939508809728,375143143408309123

  • sort
    string

    A method to sort the filtered data. Structure sorting uses the stage, group, round and match numbers. Schedule sorting uses the scheduled date. Latest results sorting uses the date at which the matches were played (not scheduled).

    Possible values: structure, schedule, latest_results

    Default: structure

Request Body

This endpoint doesn't require a request body.

Response

[206] Matches retrieved

Example
[
    {
        "id": "618954615761465416",
        "stage_id": "618983668512789184",
        "group_id": "618985165765456465",
        "round_id": "618965146546456651",
        "number": 2,
        "type": "duel",
        "status": "pending",
        "scheduled_datetime": "2015-12-31T00:00:00+00:00",
        "played_at": "2015-12-31T00:00:00+00:00",
        "opponents": [
            {
                "number": 1,
                "position": 1,
                "result": "win",
                "rank": 3,
                "forfeit": false,
                "score": 15,
                "participant": {
                    "id": "375143143408309123",
                    "name": "Jon Snow",
                    "custom_fields": {
                        "country": "UK",
                        "logo": {
                            "logo_small": "url_to_small_image",
                            "logo_medium": "url_to_medium_image",
                            "logo_large": "url_to_large_image"
                        }
                    }
                }
            }
        ]
    }
]
Structure (collection)
  • id
    string

    The id of the match and the match (they both share the same id).

    Example: "618954615761465416"

  • stage_id
    string

    The id of the stage that contains this match

    Example: "618983668512789184"

  • group_id
    string

    The id of the group that contains this match

    Example: "618985165765456465"

  • round_id
    string

    The id of the round that contains this match

    Example: "618965146546456651"

  • number
    integer

    The match number (a relative identifier within a round)

    Example: 2

  • type
    string

    The type of match

    Possible values: duel, ffa, bye

  • status
    string

    The status of the match

    Possible values: pending, running, completed

  • scheduled_datetime
    datetime|null

    The scheduled date of the match

    Format: RFC 3339 (combined date, time and utc offset)

    Example: "2015-12-31T00:00:00+00:00"

  • played_at
    datetime|null

    The timestamp on which the match was played (a result was provided)

    Format: RFC 3339 (combined date, time and utc offset)

    Example: "2015-12-31T00:00:00+00:00"

  • opponents
    array[object]

    List of match opponents.