Link Copied to clipboard

MySquadStats API Documentation

This Documentation is a Work in Progress and is subject to changes. MySquadStats is under no obligation to prioritize the updating of this API.

If your question is not addressed, pleae visit our Discord.

🔗Table of Contents

• Changes
• Authorization
• /allTimeLeaderboards
• /ping
• /players
• /playerLink
• /playerRibbons
• /playerWeapons
• /ribbons
• /ribbonRecipients
• /seasonLeaderboards
• /seasons
• /servers

🔗Changes

Below are some of the notable recent Changes to the API:

• October 16, 2026 | More than 30 requests a minute with a wrong, old or revoked Access Token from one IP (or IPv6 /64 network) now get HTTP 429 with a Retry-After header instead of Invalid Access Token. Requests with a valid Access Token are not counted. page on /allTimeLeaderboards, /ribbonRecipients, /seasonLeaderboards, /seasons and /servers must be a whole number from 1 (a fraction is dropped); hex, zero, negative or exponent values return Invalid page number. Sending a query parameter more than once or in brackets (such as search[]=x) returns Invalid query parameters. on /allTimeLeaderboards, /playerRibbons, /playerWeapons, /seasonLeaderboards, /seasons and /servers, and for sortDirection on /ribbonRecipients. If an endpoint fails unexpectedly, it now returns HTTP 500 without details of the error.
• October 15, 2026 | /playerLink now needs an Access Token, like the other endpoints, and returns Access Token is Required without one. /ping still works without one.
• October 14, 2026 | Player names, such as lastName, are now returned exactly as the player typed them. Before, many were HTML-escaped (for example O'Neil instead of O'Neil). Escape them before putting them into HTML.
• October 12, 2026 | /ribbonRecipients now sorts by timesAwarded (the default, most awarded first), firstAwarded or lastAwarded, and no longer returns an error when sortColumn is left out. Pass sortDirection=asc for ascending order. The parameter is ribbonID (capital ID).
• October 12, 2026 | Requests without an Access Token from an IPv6 address are now rate limited per /64 network, so devices that share a /64 share one limit. IP blocks on an IPv6 address also cover its whole /64.
• October 12, 2026 | If MySquadStats staff revoke a server's Access Token, all of that server's tokens stop working and return Invalid Access Token. /manage get-my-tokens shows them as revoked, and /manage regenerate-token will not issue a new one. Please create a Support Ticket to get access back.
• October 11, 2026 | Access Tokens with more than one scope (for example read and write) now get all of them. Before, some got only their first scope and returned Insufficient Access for the others.
• October 11, 2026 | Kills, wounds and revives sent by the SquadJS plugin are now saved only against the match they happened in, and a round end sent twice no longer closes the next match. No plugin update is needed.
• October 11, 2026 | Play, seeding, squad leader and commander time is now saved once per player, including when a server goes offline mid-session, and playTimeInfo on /players has one entry per server. Wins and losses are saved under the match that ended, seasonWLRatio is always a number (the number of wins when there are no losses), and end-of-season rankings and ribbons are finalized once per season. Data lost before these fixes is not restored.
• October 11, 2026 | Admins and whitelisted players (adminServers and whitelistedServers on /players) and per-weapon woundsCount and damageDealt (/playerWeapons) are now recorded reliably, as are stats the SquadJS plugin sends for players without an mssID.
• October 11, 2026 | The old URL https://mysquadstats.com/api/... has been shut down. Use https://api.mysquadstats.com/....
• October 10, 2026 | /players now needs a real search value. A 17-digit SteamID returns that player, and a name returns up to 50 players (lastName and steamID), most recently seen first; names under 3 characters must match exactly. The Steam avatar is included only for a SteamID search with avatar=true.
• October 10, 2026 | /ribbonRecipients searches now work like /players: a 17-digit SteamID matches exactly (partial SteamIDs no longer match), names under 3 characters must match exactly, and longer names match partially. Sending page, pageSize, draw, search or ribbonID more than once returns Invalid query parameters.
• October 10, 2026 | A blocked IP now gets HTTP 403 Requests from this IP address are blocked. on every API URL. Unknown URLs now return HTTP 404 instead of redirecting to /error.
• October 10, 2026 | We fixed several errors that could restart the API. Now only the request that failed gets an error, so short outages should be rarer.
• October 4, 2026 | Using the API without an Access Token is meant only for the mysquadstats.com website, and such requests can now read only the data the website shows; everything else needs a token. /playerLink and /ping still work without one, at up to 200 requests a minute per IP.
• October 4, 2026 | Requests without a valid Access Token are now limited per IP to 120 a minute, 60 a minute on search and list endpoints (such as leaderboards, players, ribbon recipients and servers), and 1,500 an hour. They must also send a User-Agent header, and pages past 50 need a token. A wrong, old or revoked token is treated the same as no token (changed October 16, 2026, see above).
• October 4, 2026 | Read Only and Read/Write Access Tokens are now limited to 300 requests a minute and 10,000 an hour per token, across every IP they are used from. Server tokens used by the SquadJS plugin are still never rate limited.
• October 4, 2026 | Rate-limit and request-check errors now use HTTP status codes with a JSON status and message: 400 (missing User-Agent, page past 50) and 429 (over a rate limit, with a Retry-After header). Token and endpoint errors, such as Invalid Access Token or Invalid dataType, still return HTTP 200 with status set to Error, so check both (changed October 16, 2026, see above).
• May 27, 2025 | The URL for the API has updated from https://mysquadstats.com/api/... to https://api.mysquadstats.com/.... The old URL is still active for the time being but will be fully shut down in the future. Exact date TBD.
• May 27, 2025 | Each endpoint on the old URL used to include in the response payload a successStatus and a successMessage. In the new API URL, the response payload has updated to instead include status and message along with the requested data if successful.
• May 27, 2025 | Most all references of dlc have been updated to mod.

🔗Authorization

Most MySquadStats Endpoints require an Access Token (/ping does not). There are a few ways to obtain an API Access Token:

1. Have the Sq License Owner Role in the OWI Hosting Discord and apply to #send-your-stats in the MySquadStats Discord. Upon approval, you will be given an API Access Token for use in our SquadJS Plugin. This token shall only be used within the SquadJS Plugin. If you require a token for other means, please see the next options.
2. Apply for a Read Only API Access Token. This type of Access Token will be granted on a case by case basis depending on your specified use and is subject to Rate Limits of 300 Requests/Minute and 10,000 Requests/Hour
3. Apply for a Read/Write API Access Token. Maybe you're creating a different way to parse the SquadGame.log instead of using SquadJS. Please DM @werewolfboy13 in Discord to discuss your use case.

🔗 /allTimeLeaderboards

GET /allTimeLeaderboards

Returns the All Time Leaderboards for the specified DLC/MOD.

Query Parameters:

  • accessToken (required) - String - The Access Token to use.
  • mod (required) - String - The MOD to return Leaderboards for.
    • "Vanilla", "MEE", "GE", "GC", "SD", "KOTH", "SPM", "ICM"
  • page - Number - The page number to return. Default is 1.
  • pageSize - Number - The number of entries to return per page. Default is 10. Max is 100.
  • sortColumn - String - The column to sort by. Available options are:
    • "eosID", "steamID", "lastName", "totalScore", "totalScoreRank", "totalWounds", "totalWoundsRank", "totalKills", "totalKillsRank", "totalDeaths", "totalDeathsRank", "totalRevives", "totalRevivesRank", "totalTimesRevived", "totalTimesRevivedRank", "totalKdRatio", "totalKdRatioRank", "totalTks", "totalTksRank", "totalTkd", "totalTkdRank", "highestKillstreak", "highestKillstreakRank"
  • sortDirection - String - The direction to sort.
    • "asc", "desc"
  • search - String - The search term to filter by.

Example:

/allTimeLeaderboards?accessToken=YOUR_ACCESS_TOKEN&mod=Vanilla&page=1&pageSize=10&sortColumn=totalScore&sortDirection=desc

🔗/ping

GET /ping

Returns a simple response to check if the API is online.

Query Parameters:

  • accessToken (optional) - String - The Access Token to use.

Example:

/ping?accessToken=YOUR_ACCESS_TOKEN

🔗/players

GET /players

Returns data for a Player.

Query Parameters:

  • accessToken (required) - String - The Access Token to use.
  • search (required) - String - The search term to find a player. SteamID or Player Name is accepted. A SteamID returns that player's data. A name returns the lastName and steamID of up to 50 matching players, most recently seen first; names shorter than 3 characters must match exactly.

Example:

/players?accessToken=YOUR_ACCESS_TOKEN&search=ignis

GET /playerLink

Returns the Player Link for a Player.

Query Parameters:

  • accessToken (required) - String - The Access Token to use.
  • steamID (optional) - String - The SteamID to find a player.
  • eosID (optional) - String - The EOSID to find a player.
  • discordID (optional) - String - The DiscordID to find a player.

Example:

/playerLink?accessToken=YOUR_ACCESS_TOKEN&steamID=76561198057101411

🔗/playerRibbons

GET /playerRibbons

Returns the Ribbons for a Player.

Query Parameters:

  • accessToken (required) - String - The Access Token to use.
  • search (required) - String - The search term to find a player. SteamID is accepted.

Example:

/playerRibbons?accessToken=YOUR_ACCESS_TOKEN&search=76561198057101411

🔗/playerWeapons

GET /playerWeapons

Returns the Weapons for a Player.

Query Parameters:

  • accessToken (required) - String - The Access Token to use.
  • search (required) - String - The search term to find a player. SteamID is accepted.

Example:

/playerWeapons?accessToken=YOUR_ACCESS_TOKEN&search=76561198057101411

🔗/ribbons

GET /ribbons

Returns the Ribbons available.

Query Parameters:

  • accessToken (required) - String - The Access Token to use.

Example:

/ribbons?accessToken=YOUR_ACCESS_TOKEN

🔗/ribbonRecipients

GET /ribbonRecipients

Returns the Ribbon Recipients.

Query Parameters:

  • accessToken (required) - String - The Access Token to use.
  • ribbonID (required) - Number - The Ribbon ID to filter.
  • page - Number - The page number to return. Default is 1.
  • pageSize - Number - The number of entries to return per page. Default is 10. Max is 100.
  • sortColumn - String - The column to sort by. Default is "timesAwarded". Available options are:
    • "timesAwarded", "firstAwarded", "lastAwarded"
  • sortDirection - String - The direction to sort. Default is "desc".
    • "asc", "desc"

Example:

/ribbonRecipients?accessToken=YOUR_ACCESS_TOKEN&ribbonID=2&page=1&pageSize=10&sortColumn=lastAwarded&sortDirection=desc

🔗/seasonLeaderboards

GET /seasonLeaderboards

Returns the Season Leaderboards for the specified DLC/MOD.

Query Parameters:

  • accessToken (required) - String - The Access Token to use.
  • mod (required) - String - The DLC/MOD to return Leaderboards for.
    • "Vanilla", "MEE", "GE", "GC", "SD", "KOTH", "SPM", "ICM"
  • season - String - The Season to return.
    • "Current", "Dev Season", "Season 1", etc
  • page - Number - The page number to return. Default is 1.
  • pageSize - Number - The number of entries to return per page. Default is 10. Max is 100.
  • sortColumn - String - The column to sort by. Available options are:
    • "eosID", "steamID", "lastName", "seasonScore", "seasonScoreRank", "seasonWounds", "seasonWoundsRank", "seasonKills", "seasonKillsRank", "seasonDeaths", "seasonDeathsRank", "seasonRevives", "seasonRevivesRank", "seasonTimesRevived", "seasonTimesRevivedRank", "seasonKdRatio", "seasonKdRatioRank", "seasonTks", "seasonTksRank", "seasonTkd", "seasonTkdRank", "highestKillstreak", "highestKillstreakRank"
  • sortDirection - String - The direction to sort.
    • "asc", "desc"
  • search - String - The search term to filter by.

Example:

/seasonLeaderboards?accessToken=YOUR_ACCESS_TOKEN&mod=Vanilla&season=Current&page=1&pageSize=10&sortColumn=seasonScore&sortDirection=desc

🔗/seasons

GET /seasons

Returns the Seasons available.

Query Parameters:

  • accessToken (required) - String - The Access Token to use.
  • page - Number - The page number to return. Default is 1.
  • pageSize - Number - The number of entries to return per page. Default is 10. Max is 100.
  • sortColumn - String - The column to sort by. Available options are:
    • "seasonName", "seasonStart", "seasonEnd", "totalPlayers", "totalMatches", "totalWounds", "totalKills", "totalDeaths", "totalRevives", "totalTeamkills"
  • sortDirection - String - The direction to sort.
    • "asc", "desc"
  • search - String - The search term to filter by. Season Name is accepted.

Example:

/seasons?accessToken=YOUR_ACCESS_TOKEN&page=1&pageSize=10&sortColumn=seasonName&sortDirection=asc&search=Dev

🔗/servers

GET /servers

Returns the Servers available.

Query Parameters:

  • accessToken (required) - String - The Access Token to use.
  • page - Number - The page number to return. Default is 1.
  • pageSize - Number - The number of entries to return per page. Default is 10. Max is 100.
  • sortColumn - String - The column to sort by. Available options are:
    • "id", "orgId", "name", "firstSeen", "lastUpdate", "version"
  • sortDirection - String - The direction to sort.
    • "asc", "desc"
  • search - String - The search term to filter by. Server Name is accepted.

Example:

/servers?accessToken=YOUR_ACCESS_TOKEN&page=1&pageSize=10&sortColumn=name&sortDirection=asc&search=PSG