---
title: "Get all matches"
method: GET
path: "/volleyball/matches"
tags: ["Volleyball.Matches"]
---

# Get all matches

`GET /volleyball/matches`

## Request

- Base URL: `https://sports.highlightly.net`
- URL: `https://sports.highlightly.net/volleyball/matches`
- Auth: none declared. Required headers: `x-rapidapi-host`, `x-rapidapi-key`
- TypeScript: <https://skmtc.dev/highlightly/apis/sports-api-highlightly/docs/volleyball/matches/get.ts> (a function with typed inputs; its response is checked against the schema)

> Refresh interval: Once a minute

> Route returns only general match information. For additional match details check the `matches/{matchId}` route. 

Retrieve a list of matches based on the requested query parameters. 

At least one primary query parameter needs to be specified before you can retrieve the data (`timezone`, `limit`, `offset` are considered secondary).

You can specify the `timezone` field in combination with the `date` query parameter to get matches relevant to your location.

There are two other important parameters. The `limit` parameter defines what the number of returned matches will be. If the number of actual matches is above the `limit` value you can make subsequent requests by increasing the `offset` value. 

Matches have different possible states they can be in:

| State        | Description |
| -----------  | ----------- |
| Not started    |  Match has not been started yet.         |
| First set  |  Match is considered in play and is in the first set.         |
| Second set  | Match is considered in play and is in the second set.          |
| Third set  |  Match is considered in play and is in the third set.          |
| Fourth set  |  Match is considered in play and is in the fourth set.          |
| Fifth set |  Match is considered in play and is in the fifth set.          |
| Finished  | Match has been concluded.          |
| Postponed  | Match has been postponed due to certain circumstances that are preventing the game from being played. Event start time will be changed to a moment in the future.           |
| Cancelled  |  Game will not be played.         |
| Awarded  |  Game awarded to one of the teams when the other forfeits or specific circumstances have been met such as insufficient players, late arrival, team withdrawl, etc.          |
| Interrupted  | An issue arose that is preventing the game from continuing. Based on the interruption the game will either resume normal play or be abandoned.          |
| Abandoned  | Considered "abandoned" when it is prematurely ended by the officials and can not be resumed or completed. In the future the game **might be** resumed from the exact point where it was halted.            |
| Unknown  | Unknown match coverage or state.          |
| To be announced  | Match's start time will be updated or competing teams are not yet known.          |

Below is an example of what you can aim to achieve with the matches endpoint:

![Volleyball matches example](https://highlightly.net/assets/img/documentation/volleyball/matches.png)

## Query parameters

- `leagueName` string
- `leagueId` number
- `date` string
- `timezone` string
- `season` number
- `homeTeamId` number
- `awayTeamId` number
- `homeTeamName` string
- `awayTeamName` string
- `countryCode` string
- `countryName` string
- `limit` number
- `offset` number

## Headers

- `x-rapidapi-host` string, required
- `x-rapidapi-key` string, required

## Response `200`

- VolleyballMatchPaginatedResponseDto
  - `data` VolleyballMatchResponseDto[], required
    - `id` number, required
    - `week` string
    - `date` string, required
    - `country` VolleyballCountryResponseDto, required
      - `code` string, required: Country code specified by the ISO 3166 standard.
      - `name` string, required
      - `logo` string, required
    - `awayTeam` VolleyballTeamResponseDto, required
      - `id` number, required
      - `logo` string
      - `name` string, required
    - `homeTeam` VolleyballTeamResponseDto, required
      - `id` number, required
      - `logo` string
      - `name` string, required
    - `league` VolleyballMatchLeagueResponseDto, required
      - `id` number, required
      - `season` number, required
      - `name` string, required
      - `logo` string
    - `state` VolleyballMatchStateResponseDto, required
      - `description` 'Not started' | 'First set' | 'Second set' | 'Third set' | 'Fourth set' | 'Fifth set' | 'Awarded' | 'Postponed' | 'Cancelled' | 'Interrupted' | 'Abandoned' | 'Finished' | 'Unknown' | 'To be announced', required: State of the match.
      - `score` VolleyballMatchScoreResponseDto, required
        - `current` string: Home - Away score for the match.
        - `firstSet` string: Home - Away score for the first set.
        - `secondSet` string: Home - Away score for the second set.
        - `thirdSet` string: Home - Away score for the third set.
        - `fourthSet` string: Home - Away score for the fourth set.
        - `fifthSet` string: Home - Away score for the fifth set.
  - `pagination` PaginationResponseDto, required
    - `totalCount` number, required: Available number of items, relevant to the provided query.
    - `offset` number, required
    - `limit` number, required
  - `plan` PlanResponseDto, required
    - `tier` string, required: Your current API subscription tier.
    - `message` string, required: Explanation message regarding your current tier.

## Other responses

- `400`: Bad request descriptive error.
- `500`: Internal server error.

---

[API](https://skmtc.dev/highlightly/apis/sports-api-highlightly.md) - [All operations](https://skmtc.dev/highlightly/apis/sports-api-highlightly/llms.txt) - [OpenAPI document](https://skmtc.dev/highlightly/apis/sports-api-highlightly/revisions/c8a366d3091f?raw)