> For the complete documentation index, see [llms.txt](https://docs.matchplay.events/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.matchplay.events/tournaments-api.md).

# Tournaments API

## Get tournament

```http
GET /api/tournaments/{tournamentId}
```

Get details for a single tournament, optionally include players, arenas and other details in the response.

**Query params**

| Name                                  | Description                                                                 |
| ------------------------------------- | --------------------------------------------------------------------------- |
| `includePlayers` (boolean)            | Set to `true` to include players                                            |
| `includeArenas` (boolean)             | Set to `true` to include arenas                                             |
| `includeBanks` (boolean)              | Set to `true` to include banks                                              |
| `includeScorekeepers` (boolean)       | Set to `true` to include scorekeepers                                       |
| `includeLocation` (boolean)           | Set to `true` to include location                                           |
| `includeEntryConfiguration` (boolean) | Set to `true` to include the entry configuration for best game tournaments  |
| `includeRsvpConfiguration` (boolean)  | Set to `true` to include RSVP configuration                                 |
| `includeLinkedTournaments` (boolean)  | Set to `true` to include linked tournaments such as qualifying and playoffs |
| `includeEvent` (boolean)              | Set to `true` to include the event this tournament is part of               |
| `includeShortcut` (boolean)           | Set to `true` to include custom link                                        |
| `includeSeries` (boolean)             | Set to `true` to include series                                             |

## Get tournament list

```http
GET /api/tournaments
```

Retrieve a list of tournaments. You can filter the list using various parameters. **Note: Do not attempt to iterate over thousands of tournaments using this endpoint.** Get in touch if you are looking to download large amounts of data.

**Query params**

| Name               | Description                                                                         |
| ------------------ | ----------------------------------------------------------------------------------- |
| `page` (integer)   | Which page of results to get                                                        |
| `limit` (integer)  | Number of results per page. Defaults to `25`, max is `100`                          |
| `owner` (integer)  | Filter to tournaments created by this user                                          |
| `played` (integer) | Filter to tournaments played by this user                                           |
| `status` (string)  | Filter to tournaments in this state. Possible values: `planned, started, completed` |
| `series` (integer) | Filter to tournaments belonging to this series                                      |

## Get tournament standings

```http
GET /api/tournaments/{tournamentId}/standings
```

Retrieve the tournament standings. **Do not request this endpoint more frequently than once every 15 seconds for tournaments that are in progress.** For completed tournaments only fetch standings once. They will never change.

## Get tournament arena summary

```http
GET /api/tournaments/{tournamentId}/summary/arenas
```

One entry per arena in the tournament with data on how many times that arena was played. This summary is only available once the tournament has been completed.

**Query params**

| Name             | Description                  |
| ---------------- | ---------------------------- |
| `page` (integer) | Which page of results to get |

## Get tournament player/arena summary

```http
GET /api/tournaments/{tournamentId}/summary/player-arenas
```

One entry per player/arena combination in the tournament with data on how many times the player played each arena and how many wins & losses the player had. This summary is only available once the tournament has been completed.

**Query params**

| Name             | Description                  |
| ---------------- | ---------------------------- |
| `page` (integer) | Which page of results to get |

## Get tournament player/opponent/arena summary

```http
GET /api/tournaments/{tournamentId}/summary/matches
```

One entry per player/opponent/arena combination in the tournament with data on how many times the player played that opponent on each arena and how many wins & losses the player had. This summary is only available once the tournament has been completed.

The data from this endpoint is intentionally duplicated. If Player A and Player B played Machine X there will be both a `playerA-playerB-machineX` entry and a `playerB-playerA-machineX`.

**Query params**

| Name             | Description                  |
| ---------------- | ---------------------------- |
| `page` (integer) | Which page of results to get |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.matchplay.events/tournaments-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.