List matches

GET

/matches

const url = 'https://api.krkplaystennis.example/v1/matches?limit=20&cursor=bWF0XzJ2YjZucDRrdGY&player_id=plr_2b7xq9mhk4&competition_id=cmp_6tw2hn8rxe&status=completed&rating_status=pending&played_after=2026-10-01T00%3A00%3A00%2B02%3A00&played_before=2026-11-01T00%3A00%3A00%2B01%3A00';
const options = {method: 'GET', headers: {'X-API-Key': '<X-API-Key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.krkplaystennis.example/v1/matches?limit=20&cursor=bWF0XzJ2YjZucDRrdGY&player_id=plr_2b7xq9mhk4&competition_id=cmp_6tw2hn8rxe&status=completed&rating_status=pending&played_after=2026-10-01T00%3A00%3A00%2B02%3A00&played_before=2026-11-01T00%3A00%3A00%2B01%3A00' \
  --header 'X-API-Key: <X-API-Key>'

Returns matches ordered by played_at, newest first. Combine filters to narrow the results.

Authorizations

ApiKeyAuth

Parameters

Query Parameters

limit

integer

default: 20 >= 1 <= 100

Maximum number of items to return.

cursor

string

The next_cursor value from the previous page. Omit it to get the first page.

Example

bWF0XzJ2YjZucDRrdGY

player_id

A player ID. Starts with plr_.

string

/^plr_[a-z0-9]{10}$/

Returns only matches this player took part in.

competition_id

A competition ID. Starts with cmp_.

string

/^cmp_[a-z0-9]{10}$/

Returns only matches in this competition.

status

How the match ended:

completed: the match was played to the end.
retired: a player stopped during the match. The match is rated on the games completed.
walkover: a player didn’t show up or withdrew before the match. The match isn’t rated.

string

Allowed values: completed retired walkover

Returns only matches with this status.

rating_status

Whether the match has affected ratings:

pending: the result is recorded, and the rating update hasn’t run yet.
rated: both players’ ratings are updated.
not_rated: the match doesn’t affect ratings, for example a walkover.

string

Allowed values: pending rated not_rated

Returns only matches with this rating status.

played_after

string format: date-time

Returns only matches played at or after this time.

Example

2026-10-01T00:00:00+02:00

played_before

string format: date-time

Returns only matches played before this time.

Example

2026-11-01T00:00:00+01:00

Responses

200

A page of matches.

application/json

object

data

required

Array<object>

object

required

A match ID. Starts with mat_.

string

/^mat_[a-z0-9]{10}$/

competition_id

required

A competition ID. Starts with cmp_.

string

/^cmp_[a-z0-9]{10}$/

venue_id

required

A venue ID. Starts with ven_.

string

/^ven_[a-z0-9]{10}$/

court_number

required

The court number at the venue. null if the organizer didn’t send it.

integer | null

>= 1

played_at

required

When the match started.

string format: date-time

player_ids

required

The two players. Every score pair uses this order.

Array<string>

>= 2 items <= 2 items

status

required

How the match ended:

completed: the match was played to the end.
retired: a player stopped during the match. The match is rated on the games completed.
walkover: a player didn’t show up or withdrew before the match. The match isn’t rated.

string

Allowed values: completed retired walkover

score

required

One of:

object
null

The score, set by set. Every pair of numbers is in the same order as player_ids.

Valid set scores depend on the competition’s match_format.games_per_set. When match_format.final_set is match_tiebreak, a match tiebreak replaces the third set. In a retired match, the last set can be unfinished.

object

sets

required

Array<object>

>= 1 items <= 3 items

object

games

required

Two non-negative integers, in the same order as player_ids.

Array<integer>

>= 2 items <= 2 items

tiebreak

Tiebreak points, only for a set that ended 7-6.

Array<integer>

>= 2 items <= 2 items

match_tiebreak

Match tiebreak points, only when the competition’s match_format.final_set is match_tiebreak.

Array<integer>

>= 2 items <= 2 items

winner_id

required

A player ID. Starts with plr_.

string

/^plr_[a-z0-9]{10}$/

retired_player_id

required

One of:

string
null

A player ID. Starts with plr_.

string

/^plr_[a-z0-9]{10}$/

rating_status

required

Whether the match has affected ratings:

pending: the result is recorded, and the rating update hasn’t run yet.
rated: both players’ ratings are updated.
not_rated: the match doesn’t affect ratings, for example a walkover.

string

Allowed values: pending rated not_rated

created_at

required

When the result was submitted.

string format: date-time

next_cursor

required

Pass this value as cursor to get the next page. null means this is the last page.

string | null

Examples

matches

Recent matches in the Kraków Autumn League

{
  "data": [
    {
      "id": "mat_4nc8xq2vbt",
      "competition_id": "cmp_6tw2hn8rxe",
      "venue_id": "ven_7hk2p9wq4m",
      "court_number": 2,
      "played_at": "2026-10-10T18:00:00+02:00",
      "player_ids": [
        "plr_2b7xq9mhk4",
        "plr_9fz3tr6wn1"
      ],
      "status": "completed",
      "score": {
        "sets": [
          {
            "games": [
              6,
              4
            ]
          },
          {
            "games": [
              3,
              6
            ]
          }
        ],
        "match_tiebreak": [
          10,
          7
        ]
      },
      "winner_id": "plr_2b7xq9mhk4",
      "retired_player_id": null,
      "rating_status": "rated",
      "created_at": "2026-10-10T20:41:00Z"
    },
    {
      "id": "mat_7rk3mw9zse",
      "competition_id": "cmp_6tw2hn8rxe",
      "venue_id": "ven_3xr8tn5cva",
      "court_number": 1,
      "played_at": "2026-10-08T19:00:00+02:00",
      "player_ids": [
        "plr_5jd8vk2lc7",
        "plr_8mq4ws1yd6"
      ],
      "status": "retired",
      "score": {
        "sets": [
          {
            "games": [
              6,
              2
            ]
          },
          {
            "games": [
              2,
              1
            ]
          }
        ]
      },
      "winner_id": "plr_5jd8vk2lc7",
      "retired_player_id": "plr_8mq4ws1yd6",
      "rating_status": "rated",
      "created_at": "2026-10-08T21:12:00Z"
    },
    {
      "id": "mat_2vb6np4ktf",
      "competition_id": "cmp_6tw2hn8rxe",
      "venue_id": "ven_7hk2p9wq4m",
      "court_number": null,
      "played_at": "2026-10-05T10:00:00+02:00",
      "player_ids": [
        "plr_9fz3tr6wn1",
        "plr_5jd8vk2lc7"
      ],
      "status": "walkover",
      "score": null,
      "winner_id": "plr_9fz3tr6wn1",
      "retired_player_id": null,
      "rating_status": "not_rated",
      "created_at": "2026-10-05T10:20:00Z"
    }
  ],
  "next_cursor": "bWF0XzJ2YjZucDRrdGY"
}

400

The request is malformed, for example a query parameter has the wrong type.

application/problem+json

An error, as RFC 9457 problem details.

object

type

required

A URL that identifies the error type and links to its documentation.

string format: uri

title

required

A short summary of the error type. It’s the same for every error of this type.

string

status

required

The HTTP status code.

integer

>= 400 <= 599

detail

required

An explanation of this occurrence of the error.

string

instance

The request path that caused the error.

string

errors

One item per invalid field or parameter. Only for invalid-request, invalid-score, and validation-failed.

Array<object>

object

pointer

required

A JSON Pointer to the invalid field in the request body, or #/ followed by the name of an invalid query parameter.

string

detail

required

What’s wrong with the field and how to fix it.

string

Examples

invalidRequest

Limit out of range

{
  "type": "https://saverio-cirillo.com/krk-plays-tennis-api/errors/#invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "The request has 1 invalid parameter.",
  "instance": "/v1/players",
  "errors": [
    {
      "pointer": "#/limit",
      "detail": "limit must be between 1 and 100."
    }
  ]
}

401

The credentials are missing, invalid, or expired.

application/problem+json

An error, as RFC 9457 problem details.

object

type

required

A URL that identifies the error type and links to its documentation.

string format: uri

title

required

A short summary of the error type. It’s the same for every error of this type.

string

status

required

The HTTP status code.

integer

>= 400 <= 599

detail

required

An explanation of this occurrence of the error.

string

instance

The request path that caused the error.

string

errors

One item per invalid field or parameter. Only for invalid-request, invalid-score, and validation-failed.

Array<object>

object

pointer

required

A JSON Pointer to the invalid field in the request body, or #/ followed by the name of an invalid query parameter.

string

detail

required

What’s wrong with the field and how to fix it.

string

Examples

unauthenticated

Missing API key

{
  "type": "https://saverio-cirillo.com/krk-plays-tennis-api/errors/#unauthenticated",
  "title": "Authentication required",
  "status": 401,
  "detail": "Send a valid API key in the X-API-Key header.",
  "instance": "/v1/players/plr_2b7xq9mhk4"
}

429

You sent too many requests. Wait for the number of seconds in Retry-After, then retry.

application/problem+json

An error, as RFC 9457 problem details.

object

type

required

A URL that identifies the error type and links to its documentation.

string format: uri

title

required

A short summary of the error type. It’s the same for every error of this type.

string

status

required

The HTTP status code.

integer

>= 400 <= 599

detail

required

An explanation of this occurrence of the error.

string

instance

The request path that caused the error.

string

errors

One item per invalid field or parameter. Only for invalid-request, invalid-score, and validation-failed.

Array<object>

object

pointer

required

A JSON Pointer to the invalid field in the request body, or #/ followed by the name of an invalid query parameter.

string

detail

required

What’s wrong with the field and how to fix it.

string

Examples

rateLimited

Rate limit reached

{
  "type": "https://saverio-cirillo.com/krk-plays-tennis-api/errors/#rate-limited",
  "title": "Rate limit reached",
  "status": 429,
  "detail": "This API key is limited to 60 requests per minute. Retry after 30 seconds.",
  "instance": "/v1/matches"
}

Headers

Retry-After

integer

>= 1

Number of seconds to wait before you retry.