csgostats APIcsgostats.gg ↗
Access CS2 player stats, match history, weapon breakdowns, rank data, and leaderboards via the csgostats.gg API. 7 endpoints covering players and matches.
What is the csgostats API?
The csgostats.gg API exposes 7 endpoints covering CS2 player profiles, detailed match history, weapon-level statistics, and competitive leaderboards. Starting with get_player_stats, you can retrieve per-player summaries (kills, deaths, assists, headshots, damage, rounds) alongside a full weapons breakdown showing kills, HS percentage, and accuracy for every weapon a player has used.
curl -X GET 'https://api.parse.bot/scraper/cc6a7862-b65e-4a6f-b3b7-fd13a5228d53/get_player_profile?player_id=76561198088771412' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace csgostats-gg-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""CSStats.gg SDK — CS2 player stats, matches, and leaderboards."""
from parse_apis.csgostats_gg_api import CSStats, LeaderboardMode, Source, MatchNotFound
client = CSStats()
# Browse the Premier leaderboard — limit caps total items fetched.
for entry in client.leaderboardentries.list(mode=LeaderboardMode.PREMIER, limit=5):
print(entry.name, entry.current_rank, entry.wins)
# Drill into a specific player using constructible Player resource.
player = client.player(steam_id="76561198088771412")
# Get detailed stats for that player filtered by source.
stats = player.stats(source=Source.CS2)
print(stats.summary.played, stats.summary.kills, stats.summary.headshots)
if stats.weapons:
top = stats.weapons[0]
print(top.weapon, top.kills, top.hs_pct)
# List this player's recent matches.
match = player.matches.list(limit=1).first()
if match:
print(match.match_id, match.map, match.score, match.kills)
# Fetch full match details with typed error handling.
try:
detail = client.matches.get(match_id="455825684")
for team in detail.teams:
print(team.team_name, team.score)
for p in team.players[:2]:
print(f" {p.name} {p.steam_id}")
except MatchNotFound as exc:
print(f"Match gone: {exc.match_id}")
# Global recent matches feed.
recent = client.recentmatches.list(limit=3).first()
if recent:
print(recent.match_id, recent.map, recent.score, recent.date)
print("exercised: leaderboardentries.list / player.stats / player.matches.list / matches.get / recentmatches.list")
Get player profile overview including display name, Steam avatar URL, and current rank images across all game modes (CS2, Premier, Wingman, etc.). Each rank entry includes a rank_image URL and a type indicating whether it is the current rank or best achieved.
| Param | Type | Description |
|---|---|---|
| player_idrequired | string | Steam ID of the player (17-digit numeric string, e.g. 76561198779774220) |
{
"type": "object",
"fields": {
"name": "string, player display name",
"ranks": "array of rank objects with rank_image (URL) and type (e.g. rank, best)",
"avatar": "string, URL to Steam avatar image",
"steam_id": "string, the queried Steam ID"
},
"sample": {
"data": {
"name": "John Doe",
"ranks": [
{
"type": "rank",
"rank_image": "https://static.csstats.gg/images/ranks/16.png"
},
{
"type": "best",
"rank_image": "https://static.csstats.gg/images/ranks/16.png"
}
],
"avatar": "https://avatars.steamstatic.com/d2e21dcf852030f696afc6a28ef7336774f05b6f_full.jpg",
"steam_id": "76561198088771412"
},
"status": "success"
}
}About the csgostats API
Player Data
The get_player_profile endpoint returns a player's display name, Steam avatar URL, and an array of rank objects — each with a rank_image URL and a type field that distinguishes the player's current rank from their historical best. The player_id parameter accepts a 17-digit Steam ID. The get_player_stats endpoint adds filtering by date (7d, 30d, 6mo, 12mo), maps, modes, platforms, and source (cs2 or csgo), letting you narrow statistics to a specific time window or game mode. The summary object returns aggregate counts for played, won, lost, tied, kills, deaths, assists, headshots, damage, and rounds.
Match History and Details
get_player_matches returns a paginated list of a player's matches via an offset parameter, with each match object carrying match_id, date, map, score, kills, deaths, assists, and a url. The count field tells you the total number of recorded matches for that player. Full per-player scoreboard data for any match is available through get_match_details, which accepts a match_id and returns both teams with their team_name, score, and a players array containing each player's name, steam_id, avatar, rank_image, and a stats array of numeric values.
Leaderboards and Global Feed
get_leaderboard accepts a mode parameter (premier or competitive) and returns ranked entries with rank, name, steam_id, wins, and current_rank score. get_recent_matches requires no parameters and returns the 50 most recent matches tracked globally on csgostats.gg, each with match_id, relative date, map, score, and a direct url. get_player_played_with returns an array of players that the queried Steam ID has frequently shared matches with.
The csgostats API is a managed, monitored endpoint for csgostats.gg — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when csgostats.gg changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official csgostats.gg API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track a player's kill/death ratio and headshot percentage over a 30-day rolling window using
get_player_statswith thedatefilter. - Build a match review tool that pulls the full team scoreboard for any match via
get_match_detailsusing IDs sourced fromget_player_matches. - Rank players on a tournament platform by pulling Premier or Competitive leaderboard positions from
get_leaderboard. - Display a player's current and best-ever rank images in a profile card using the
ranksarray fromget_player_profile. - Monitor recently played matches site-wide with
get_recent_matchesto surface trending maps or detect notable game sessions. - Identify frequent teammates or opponents for a player using
get_player_played_withand cross-reference their stats. - Compare weapon accuracy across players by aggregating the
weaponsarray returned byget_player_statsfor multiple Steam IDs.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does csgostats.gg have an official developer API?+
What filters are available on get_player_stats?+
date (7d, 30d, 6mo, 12mo), maps, modes, platforms, source (cs2 or csgo), and a vac filter. These can be combined to scope the returned summary and weapons breakdown to a specific subset of a player's history.How does pagination work in get_player_matches?+
offset parameter is a 0-based page index, and the count field in each response gives the total match count for the player so you can determine how many pages to request.Does the API expose CS2 Premier rating numbers or only rank images?+
get_player_profile returns rank images and type labels (current vs. best) rather than raw numeric rating values. Numeric rating scores are available for leaderboard entries via get_leaderboard, which returns a current_rank field per entry. You can fork this API on Parse and revise it to surface numeric rating values directly on player profile responses.