Get a match

GET

/matches/{match_id}

const url = 'https://api.krkplaystennis.example/v1/matches/mat_4nc8xq2vbt';
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/mat_4nc8xq2vbt \
  --header 'X-API-Key: <X-API-Key>'

Returns a match, its score, and its rating status.

Authorizations

ApiKeyAuth

Parameters

Path Parameters

match_id

required

A match ID. Starts with mat_.

string

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

The match ID.

Responses

200

The match.

application/json

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

Examples

Completed match, decided in a match tiebreak

{
  "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"
}

Retired match, rated on the games completed

{
  "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"
}

Walkover, not rated

{
  "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"
}

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"
}

404

No resource exists with this ID.

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

notFound

Unknown player ID

{
  "type": "https://saverio-cirillo.com/krk-plays-tennis-api/errors/#not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No player exists with the ID plr_0000000000.",
  "instance": "/v1/players/plr_0000000000"
}

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.