leaderboard_read
Read onlyThe game's leaderboard as its page displays it: one entry per player, best first, with rank, score_id, player (a pseudonymous id, or for a score posted from the game's page the player's username as the page displays it), score, verified (a replay of the round reproduced it), source (page, origin or room: what posted it), build and when; plus hidden, the scores taken off the board (removed with score_remove, with its reason, or rejected because their replay did not reproduce them).
/api/agent/leaderboardBehavior
The game's leaderboard as its page displays it: one entry per player, best first, with rank, score_id, player (a pseudonymous id, or for a score posted from the game's page the player's username as the page displays it), score, verified (a replay of the round reproduced it), source (page, origin or room: what posted it), build and when; plus hidden, the scores taken off the board (removed with score_remove, with its reason, or rejected because their replay did not reproduce them).
preview true reads the preview builds' board instead of the public one; limit is 1-50 (10 by default). A game with boards (leaderboards_configure) answers boards (every board, with how many split values each has seen) and read (the board read: board names it, the primary one by default; split, its first value by default; period current by default, previous, or a period's key such as 2026-10-08, 2026-W41 or 2026-10), and each entry carries value, verified, source (origin, room or replay), pending (its replay is still running) and posts.
Nothing here posts a score: a game posts its own through the SDK (engine_docs { engine: "sdk", doc: "SDK.md", section: "Rounds and scores" }, and "Leaderboards" for boards).
Input parameters
previewOptionalbooleanlimitOptionalinteger- Minimum: 1
- Maximum: 50
boardOptionalstring- Pattern: ^[a-z][a-z0-9-]{0,31}$
splitOptionalstring- Min. length: 1
- Max. length: 40
periodOptionalstring- Min. length: 3
- Max. length: 10
The descriptions above include conditional requirements. The full schema below shows structural validation; runtime checks also apply.
JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"preview": {
"type": "boolean"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50
},
"board": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]{0,31}$"
},
"split": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"period": {
"type": "string",
"minLength": 3,
"maxLength": 10
}
},
"additionalProperties": false
}Use its name in your connected MCP client. For the HTTP API, the route is relative to your Convex site URL and requires your agent key as a bearer token. Keep the key on the agent side, outside a game build.