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

# Get all matches

`GET /cricket/matches`

## Request

- Base URL: `https://sports.highlightly.net`
- URL: `https://sports.highlightly.net/cricket/matches`
- Auth: none declared. Required headers: `x-rapidapi-host`, `x-rapidapi-key`
- TypeScript: <https://skmtc.dev/highlightly/apis/sports-api-highlightly/docs/cricket/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 |
| -----------  | ----------- |
| Finished  | Match has been concluded.          |
| Unknown  | The status of the match is not known.         |
| No live coverage |  There is no live coverage for the match. |
| In play | The match is currently in progress. |
| Stumps | The end of a day's play in a multi-day match (e.g. Test match). |
| Lunch | The break taken during lunch time in a match. |
| Innings break | The interval between the end of one innings and the start of the next. |
| Drinks | A short break for players to have drinks. |
| Timeout | A strategic break taken during the match. |
| Tea | The break taken during tea time in a match, typically in Test matches. |
| Scheduled    |  The match is planned and scheduled to be played.        |
| Match delayed  | The match start or continuation is delayed, often due to weather or other interruptions.           |
| Cancelled  |  The match has been cancelled and will not be played.        |
| 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.           |
| Abandoned  | 	The match has started but is stopped and will not continue, typically due to weather or other uncontrollable circumstances.  |

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

![Cricket matches example](https://highlightly.net/assets/img/documentation/cricket/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
- `homeTeamAbbreviation` string
- `awayTeamAbbreviation` string

## Headers

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

## Response `200`

- CricketMatchPaginatedResponseDto
  - `data` CricketMatchResponseDto[], required
    - `id` string, required
    - `endDate` string, required
    - `startDate` string, required
    - `startTime` string
    - `country` CricketCountryResponseDto, required
      - `code` string, required: Country code specified by the ISO 3166 standard.
      - `name` string, required
      - `logo` string, required
    - `awayTeam` CricketTeamResponseDto, required
      - `id` string, required
      - `logo` string
      - `name` string, required
      - `abbreviation` string, required
    - `homeTeam` CricketTeamResponseDto, required
      - `id` string, required
      - `logo` string
      - `name` string, required
      - `abbreviation` string, required
    - `league` CricketMatchLeagueResponseDto, required
      - `id` string, required
      - `season` number, required
      - `name` string, required
      - `logo` string
    - `format` string: Cricket match format, e.g. T20, ODI, TEST
    - `dayType` 'SINGLE' | 'MULTI': Information that tells us whether the match will be played across multiple days
    - `state` CricketMatchStateResponseDto, required
      - `description` 'Finished' | 'Unknown' | 'No live coverage' | 'In play' | 'Stumps' | 'Lunch' | 'Innings break' | 'Drinks' | 'Timeout' | 'Tea' | 'Scheduled' | 'Match delayed' | 'Cancelled' | 'Abandoned' | 'Postponed', required: State of the match.
      - `report` string: Descriptive report of the match based on the match status.
      - `teams` CricketMatchScoreTeamsDto, required
        - `away` CricketMatchScoreTeamAwayDto, required
          - `info` string
          - `score` string
        - `home` CricketMatchScoreTeamHomeDto, required
          - `info` string
          - `score` string
  - `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)