List a player's rating history
const url = 'https://api.krkplaystennis.example/v1/players/plr_2b7xq9mhk4/rating-history?limit=20&cursor=bWF0XzJ2YjZucDRrdGY';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/players/plr_2b7xq9mhk4/rating-history?limit=20&cursor=bWF0XzJ2YjZucDRrdGY' \ --header 'X-API-Key: <X-API-Key>'Returns every change to a player’s rating or confidence, newest first. Each entry includes the reason for the change. Entries caused by a match also include the inputs to the calculation, so you can reproduce the change by hand.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”A player ID. Starts with plr_.
The player ID.
Query Parameters
Section titled “Query Parameters”Maximum number of items to return.
The next_cursor value from the previous page. Omit it to get the first page.
Example
bWF0XzJ2YjZucDRrdGYResponses
Section titled “Responses”A page of rating history entries, newest first.
object
object
A rating history entry ID. Starts with rtg_.
A player ID. Starts with plr_.
When the change was applied.
object
Why the rating or confidence changed:
initial_assessment: the starting rating, set from the self-assessed NTRP level.match_result: a rated match. Thecalculationobject has the inputs.inactivity: confidence dropped after a period without rated matches. The rating value doesn’t change.
A one-sentence explanation of the change, for display to players.
A rating. New players start between 1000 and 1800, based on their self-assessed NTRP level.
value_after minus value_before. null for initial_assessment.
How settled a rating is, from 0 to 100. New players start at 20. Each rated match adds 10, up to 95. After 60 days without a rated match, confidence drops by 5 every 30 days, down to 20.
The inputs to a match rating change. The change is k_factor × (actual_score - expected_score), rounded to the nearest integer.
object
A player ID. Starts with plr_.
A rating. New players start between 1000 and 1800, based on their self-assessed NTRP level.
The player’s chance of winning before the match, from 0 to 1. It’s 1 / (1 + 10^((opponent_rating - rating) / 400)), rounded to 3 decimal places.
1 for a win and 0 for a loss. For a retired match, the share of games the player won, rounded to 3 decimal places. A completed match tiebreak counts as one game.
The maximum number of points a rating can move in one match. It’s 48 when confidence is below 40, 32 when confidence is from 40 to 69, and 16 when confidence is 70 or higher.
Pass this value as cursor to get the next page. null means this is the last page.
Examples
Ola's history after one rated match
{ "data": [ { "id": "rtg_6ym2kd9qrz", "player_id": "plr_2b7xq9mhk4", "occurred_at": "2026-10-10T20:43:12Z", "reason": { "code": "match_result", "match_id": "mat_4nc8xq2vbt", "explanation": "Won against Kasia W. (1520). Expected score 0.334, actual score 1. K-factor 48 because confidence was 20." }, "value_before": 1400, "value_after": 1432, "change": 32, "confidence_before": 20, "confidence_after": 30, "calculation": { "opponent_id": "plr_9fz3tr6wn1", "opponent_rating": 1520, "expected_score": 0.334, "actual_score": 1, "k_factor": 48 } }, { "id": "rtg_1pt8xv4hcn", "player_id": "plr_2b7xq9mhk4", "occurred_at": "2026-09-02T08:15:00Z", "reason": { "code": "initial_assessment", "match_id": null, "explanation": "Starting rating from a self-assessed NTRP level of 3.5." }, "value_before": null, "value_after": 1400, "change": null, "confidence_before": null, "confidence_after": 20, "calculation": null } ], "next_cursor": null}The request is malformed, for example a query parameter has the wrong type.
An error, as RFC 9457 problem details.
object
A URL that identifies the error type and links to its documentation.
A short summary of the error type. It’s the same for every error of this type.
The HTTP status code.
An explanation of this occurrence of the error.
The request path that caused the error.
One item per invalid field or parameter. Only for invalid-request, invalid-score, and validation-failed.
object
A JSON Pointer to the invalid field in the request body, or #/ followed by the name of an invalid query parameter.
What’s wrong with the field and how to fix it.
Examples
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." } ]}The credentials are missing, invalid, or expired.
An error, as RFC 9457 problem details.
object
A URL that identifies the error type and links to its documentation.
A short summary of the error type. It’s the same for every error of this type.
The HTTP status code.
An explanation of this occurrence of the error.
The request path that caused the error.
One item per invalid field or parameter. Only for invalid-request, invalid-score, and validation-failed.
object
A JSON Pointer to the invalid field in the request body, or #/ followed by the name of an invalid query parameter.
What’s wrong with the field and how to fix it.
Examples
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"}No resource exists with this ID.
An error, as RFC 9457 problem details.
object
A URL that identifies the error type and links to its documentation.
A short summary of the error type. It’s the same for every error of this type.
The HTTP status code.
An explanation of this occurrence of the error.
The request path that caused the error.
One item per invalid field or parameter. Only for invalid-request, invalid-score, and validation-failed.
object
A JSON Pointer to the invalid field in the request body, or #/ followed by the name of an invalid query parameter.
What’s wrong with the field and how to fix it.
Examples
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"}You sent too many requests. Wait for the number of seconds in Retry-After, then retry.
An error, as RFC 9457 problem details.
object
A URL that identifies the error type and links to its documentation.
A short summary of the error type. It’s the same for every error of this type.
The HTTP status code.
An explanation of this occurrence of the error.
The request path that caused the error.
One item per invalid field or parameter. Only for invalid-request, invalid-score, and validation-failed.
object
A JSON Pointer to the invalid field in the request body, or #/ followed by the name of an invalid query parameter.
What’s wrong with the field and how to fix it.
Examples
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
Section titled “Headers”Number of seconds to wait before you retry.
Example
30© 2026 Saverio Cirillo · KRKplaysTennis is a fictional API · Built with Starlight