# Leaderboards

## Get app global leaderboards

> Get leaderboards for all mini game types and default games for the authenticated app. Optionally filter by a specific mini game type ID. For games without a mini game type, the miniGameTypeName is not present.

```json
{"openapi":"3.0.0","info":{"title":"Meshmap API v1","version":"1.0.0"},"servers":[{"url":"/api/v1","description":"API v1 base URL"}],"security":[{"AppAPIKey":[]}],"components":{"securitySchemes":{"AppAPIKey":{"type":"apiKey","in":"header","name":"x-app-api-key","description":"App API key in format: <key>"}},"schemas":{"GlobalLeaderboardSchema":{"type":"object","required":["leaderboards"],"properties":{"leaderboards":{"type":"array","items":{"$ref":"#/components/schemas/MiniGameLeaderboardSchema"},"nullable":true,"description":"List of leaderboards for each mini game type and default. Each leaderboard includes player profile images and additional player details."}}},"MiniGameLeaderboardSchema":{"type":"object","properties":{"miniGameTypeId":{"type":"string","nullable":true,"description":"Mini game type ID (null for default leaderboard)"},"miniGameTypeName":{"type":"string","nullable":true,"description":"Mini game type name (null for default leaderboard)"},"leaderboard":{"type":"array","items":{"$ref":"#/components/schemas/LeaderboardPlayerSchema"},"nullable":true,"description":"List of top players for this mini game type"}}},"LeaderboardPlayerSchema":{"type":"object","required":["playerId","playerDisplayName","playerScore","createdAt","updatedAt","gameSessionId"],"properties":{"playerId":{"type":"string","description":"Player ID"},"playerDisplayName":{"type":"string","description":"Player display name"},"playerScore":{"type":"number","description":"Player score"},"playerImageUrl":{"type":"string","nullable":true,"description":"URL to player's profile image"},"createdAt":{"type":"string","format":"date-time","description":"Score creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Score last update timestamp"},"gameSessionId":{"type":"string","description":"Game session ID"},"userId":{"type":"string","nullable":true,"description":"Associated user ID"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"oneOf":[{"type":"string","description":"Error message"},{"type":"array","items":{"type":"object","required":["code","message","path"],"properties":{"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Error message"},"path":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"number"}]},"description":"Error path"}}}}]}}}}},"paths":{"/apps/global-leaderboards":{"get":{"summary":"Get app global leaderboards","description":"Get leaderboards for all mini game types and default games for the authenticated app. Optionally filter by a specific mini game type ID. For games without a mini game type, the miniGameTypeName is not present.","tags":["Leaderboards"],"parameters":[{"name":"miniGameTypeId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional mini game type ID to filter leaderboards for a specific game type. If not provided, leaderboards for all game types will be returned."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":10},"description":"Maximum number of players to return per leaderboard. Defaults to 10 if not specified."}],"responses":{"200":{"description":"Leaderboards retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalLeaderboardSchema"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.meshmap.com/api/core/leaderboards.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.