Counter-Strike 2 API

Welcome to the BALLDONTLIE Counter-Strike 2 (CS2) API, the best esports API on the planet. This API contains comprehensive data for professional Counter-Strike 2 matches, tournaments, teams, and players. An API key is required. You can obtain an API key by creating a free account on our website. Read the authentication section to learn how to use the API key.

Take a look at our other APIs.

Join us on discord.

AI-Powered Integration

Using the OpenAPI Specification with AI

Our complete OpenAPI specification allows AI assistants to automatically understand and interact with our API. Simply share the spec URL with your AI assistant and describe what you want to build—the AI will handle the technical implementation.

Getting Started with AI:

Copy this URL: https://www.balldontlie.io/openapi.yml
Share it with your preferred AI assistant (ChatGPT, Claude, Gemini, etc.)
Tell the AI what you want to build (e.g., "Create a dashboard showing upcoming CS2 tournaments")
The AI will read the OpenAPI spec and write the code for you

Example prompts to try:

"Using the OpenAPI spec at https://www.balldontlie.io/openapi.yml, show me how to get FaZe Clan's map pool statistics"
"Read the BALLDONTLIE OpenAPI spec and create a Python script that fetches upcoming CS2 matches"
"Help me understand the available CS2 endpoints from this OpenAPI spec: https://www.balldontlie.io/openapi.yml"

This makes it incredibly easy for non-technical users, analysts, and researchers to leverage our esports data without needing to learn programming from scratch.

Google Sheets Integration

Our Google Sheets integration lets you access all the same data available through our API using simple spreadsheet formulas. Perfect for fantasy sports tracking, betting analysis, and sports research.

Quick Start:

Get your API key from app.balldontlie.io
Copy our Google Sheets script
Paste it into your Google Sheet (Extensions > Apps Script)
Start using functions in your cells

Example functions:

=BDL_CS_TEAMS() - Get all teams
=BDL_CS_PLAYERS("search") - Search for players
=BDL_CS_MATCHES("2026-01-27") - Get matches by date
=BDL_CS_STANDINGS(2025) - Get standings

For full setup instructions and the complete list of 150+ functions, see our Google Sheets Integration Guide.

Account Tiers

There are three different account tiers which provide you access to different types of data. Visit our website to create an account for free.

Paid tiers do not apply across sports. The tier you purchase for CS2 will not automatically be applied to other sports. You can purchase the ALL-ACCESS ($299.99/mo) tier to get access to every endpoint for every sport.

Read the table below to see the breakdown.

Endpoint	Free	ALL-STAR	GOAT
Teams	Yes	Yes	Yes
Players	Yes	Yes	Yes
Tournaments	Yes	Yes	Yes
Tournament Teams	Yes	Yes	Yes
Team Map Pool	No	Yes	Yes
Rankings	No	Yes	Yes
Matches	No	No	Yes
Match Maps	No	No	Yes
Match Map Stats	No	No	Yes
Player Match Stats	No	No	Yes
Player Match Map Stats	No	No	Yes
Player Accuracy Stats	No	No	Yes

The feature breakdown per tier is shown in the table below.

Tier	Requests / Min	$USD / mo.
GOAT	600	39.99
ALL-STAR	60	9.99
Free	5	0

Authentication

curl "api_endpoint_here" -H "Authorization: YOUR_API_KEY"

fetch("api_endpoint_here", {
  headers: {
    Authorization: "YOUR_API_KEY",
  },
});

import requests

response = requests.get(
    "api_endpoint_here",
    headers={"Authorization": "YOUR_API_KEY"}
)

BALLDONTLIE uses API keys to allow access to the API. You can register for a new API key at our developer portal.

BALLDONTLIE expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: YOUR_API_KEY

You must replace YOUR_API_KEY with your personal API key.

Pagination

All paginated endpoints support cursor-based pagination. The API returns a meta object containing pagination information:

{
  "data": [...],
  "meta": {
    "next_cursor": 123,
    "per_page": 25
  }
}

To fetch the next page, include the cursor query parameter:

curl "https://api.balldontlie.io/cs/v1/teams?cursor=123&per_page=25" \
  -H "Authorization: YOUR_API_KEY"

Parameters: - cursor (optional): The cursor value from the previous response's meta.next_cursor - per_page (optional): Number of results per page (default: 25, max: 100)

Teams

Get All Teams

curl "https://api.balldontlie.io/cs/v1/teams?per_page=25" \
  -H "Authorization: YOUR_API_KEY"

fetch("https://api.balldontlie.io/cs/v1/teams?per_page=25", {
  headers: {
    Authorization: "YOUR_API_KEY",
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data));

import requests

response = requests.get(
    "https://api.balldontlie.io/cs/v1/teams",
    headers={"Authorization": "YOUR_API_KEY"},
    params={"per_page": 25}
)

data = response.json()

{
  "data": [
    {
      "id": 631,
      "name": "FURIA",
      "slug": "furia",
      "short_name": "FURIA"
    },
    {
      "id": 650,
      "name": "Vitality",
      "slug": "vitality",
      "short_name": "VIT"
    },
    {
      "id": 765,
      "name": "Natus Vincere",
      "slug": "natus-vincere",
      "short_name": "NAVI"
    }
  ],
  "meta": {
    "next_cursor": 765,
    "per_page": 25
  }
}

This endpoint retrieves all CS2 teams.

HTTP Request

GET https://api.balldontlie.io/cs/v1/teams

Query Parameters

Parameter	Type	Required	Description
cursor	number	No	Pagination cursor from previous response
per_page	number	No	Number of results per page (max: 100)
search	string	No	Search teams by name

Get a Specific Team

curl "https://api.balldontlie.io/cs/v1/teams/1" \
  -H "Authorization: YOUR_API_KEY"

fetch("https://api.balldontlie.io/cs/v1/teams/1", {
  headers: {
    Authorization: "YOUR_API_KEY",
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data));

import requests

response = requests.get(
    "https://api.balldontlie.io/cs/v1/teams/1",
    headers={"Authorization": "YOUR_API_KEY"}
)

data = response.json()

{
  "data": {
    "id": 631,
    "name": "FURIA",
    "slug": "furia",
    "short_name": "FURIA"
  }
}

This endpoint retrieves a specific team.

HTTP Request

GET https://api.balldontlie.io/cs/v1/teams/<ID>

URL Parameters

Parameter	Description
ID	The ID of the team

Players

Get All Players

curl "https://api.balldontlie.io/cs/v1/players?per_page=25" \
  -H "Authorization: YOUR_API_KEY"

fetch("https://api.balldontlie.io/cs/v1/players?per_page=25", {
  headers: {
    Authorization: "YOUR_API_KEY",
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data));

import requests

response = requests.get(
    "https://api.balldontlie.io/cs/v1/players",
    headers={"Authorization": "YOUR_API_KEY"},
    params={"per_page": 25}
)

data = response.json()

{
  "data": [
    {
      "id": 294,
      "nickname": "ZywOo",
      "first_name": "Mathieu",
      "last_name": "Herbaut",
      "full_name": "Mathieu Herbaut",
      "team": {
        "id": 650,
        "name": "Vitality",
        "short_name": "VIT"
      },
      "age": 25,
      "birthday": "2000-11-09",
      "steam_id": "18452",
      "is_active": true
    }
  ],
  "meta": {
    "next_cursor": 295,
    "per_page": 25
  }
}

This endpoint retrieves all CS2 players.

HTTP Request

GET https://api.balldontlie.io/cs/v1/players

Query Parameters

Parameter	Type	Required	Description
cursor	number	No	Pagination cursor from previous response
per_page	number	No	Number of results per page (max: 100)
search	string	No	Search players by nickname or name
team_id	number	No	Filter by team ID
active	boolean	No	Filter by active status

Get a Specific Player

curl "https://api.balldontlie.io/cs/v1/players/1" \
  -H "Authorization: YOUR_API_KEY"

fetch("https://api.balldontlie.io/cs/v1/players/1", {
  headers: {
    Authorization: "YOUR_API_KEY",
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data));

import requests

response = requests.get(
    "https://api.balldontlie.io/cs/v1/players/1",
    headers={"Authorization": "YOUR_API_KEY"}
)

data = response.json()

{
  "data": {
    "id": 294,
    "nickname": "ZywOo",
    "first_name": "Mathieu",
    "last_name": "Herbaut",
    "full_name": "Mathieu Herbaut",
    "team": {
      "id": 650,
      "name": "Vitality",
      "short_name": "VIT"
    },
    "age": 25,
    "birthday": "2000-11-09",
    "steam_id": "18452",
    "is_active": true
  }
}

This endpoint retrieves a specific player.

HTTP Request

GET https://api.balldontlie.io/cs/v1/players/<ID>

URL Parameters

Parameter	Description
ID	The ID of the player

Tournaments

Get All Tournaments

curl "https://api.balldontlie.io/cs/v1/tournaments?per_page=25" \
  -H "Authorization: YOUR_API_KEY"

fetch("https://api.balldontlie.io/cs/v1/tournaments?per_page=25", {
  headers: {
    Authorization: "YOUR_API_KEY",
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data));

import requests

response = requests.get(
    "https://api.balldontlie.io/cs/v1/tournaments",
    headers={"Authorization": "YOUR_API_KEY"},
    params={"per_page": 25}
)

data = response.json()

{
  "data": [
    {
      "id": 2353,
      "name": "PGL Major Singapore 2026",
      "slug": "pgl-major-singapore-2026",
      "tier": "s",
      "start_date": "2026-11-25",
      "end_date": "2026-12-13",
      "prize_pool": 1250000,
      "prize_pool_currency": "USD",
      "location": null,
      "country": null,
      "is_online": false,
      "status": "upcoming"
    },
    {
      "id": 2351,
      "name": "BLAST Rivals Fall 2026",
      "slug": "blast-rivals-fall-2026",
      "tier": "s",
      "start_date": "2026-11-11",
      "end_date": "2026-11-15",
      "prize_pool": 1000000,
      "prize_pool_currency": "USD",
      "location": null,
      "country": null,
      "is_online": false,
      "status": "upcoming"
    }
  ],
  "meta": {
    "next_cursor": 2351,
    "per_page": 25
  }
}

This endpoint retrieves all CS2 tournaments.

HTTP Request

GET https://api.balldontlie.io/cs/v1/tournaments

Query Parameters

Parameter	Type	Required	Description
cursor	number	No	Pagination cursor from previous response
per_page	number	No	Number of results per page (max: 100)
search	string	No	Search tournaments by name

Get a Specific Tournament

curl "https://api.balldontlie.io/cs/v1/tournaments/1" \
  -H "Authorization: YOUR_API_KEY"

fetch("https://api.balldontlie.io/cs/v1/tournaments/1", {
  headers: {
    Authorization: "YOUR_API_KEY",
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data));

import requests

response = requests.get(
    "https://api.balldontlie.io/cs/v1/tournaments/1",
    headers={"Authorization": "YOUR_API_KEY"}
)

data = response.json()

{
  "data": {
    "id": 1,
    "name": "BLAST Premier Spring Final 2024",
    "slug": "blast-premier-spring-final-2024",
    "tier": "S",
    "start_date": "2024-06-12",
    "end_date": "2024-06-16",
    "prize_pool": 425000,
    "prize_pool_currency": "USD",
    "location": "London",
    "country": "United Kingdom",
    "is_online": false,
    "status": "finished"
  }
}

This endpoint retrieves a specific tournament.

HTTP Request

GET https://api.balldontlie.io/cs/v1/tournaments/<ID>

URL Parameters

Parameter	Description
ID	The ID of the tournament

Tournament Teams

Get Tournament Teams

curl "https://api.balldontlie.io/cs/v1/tournament_teams?tournament_id=1" \
  -H "Authorization: YOUR_API_KEY"

fetch("https://api.balldontlie.io/cs/v1/tournament_teams?tournament_id=1", {
  headers: {
    Authorization: "YOUR_API_KEY",
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data));

import requests

response = requests.get(
    "https://api.balldontlie.io/cs/v1/tournament_teams",
    headers={"Authorization": "YOUR_API_KEY"},
    params={"tournament_id": 1}
)

data = response.json()

{
  "data": [
    {
      "id": 610,
      "name": "Copenhagen Flames",
      "short_name": "CF"
    },
    {
      "id": 580,
      "name": "GamerLegion",
      "short_name": "GL"
    },
    {
      "id": 734,
      "name": "ENCE",
      "short_name": "ENCE"
    },
    {
      "id": 735,
      "name": "MIBR",
      "short_name": "MIBR"
    },
    {
      "id": 1244,
      "name": "Spirit Academy",
      "short_name": "TS.A"
    }
  ]
}

This endpoint retrieves all teams participating in a specific tournament.

HTTP Request

GET https://api.balldontlie.io/cs/v1/tournament_teams

Query Parameters

Parameter	Type	Required	Description
tournament_id	number	Yes	The ID of the tournament

Team Map Pool

Get Team Map Pool Stats

curl "https://api.balldontlie.io/cs/v1/team_map_pool?team_id=1" \
  -H "Authorization: YOUR_API_KEY"

fetch("https://api.balldontlie.io/cs/v1/team_map_pool?team_id=1", {
  headers: {
    Authorization: "YOUR_API_KEY",
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data));

import requests

response = requests.get(
    "https://api.balldontlie.io/cs/v1/team_map_pool",
    headers={"Authorization": "YOUR_API_KEY"},
    params={"team_id": 1}
)

data = response.json()

{
  "data": [
    {
      "team_id": 631,
      "map_name": "de_nuke",
      "matches_played": 2,
      "wins": 2,
      "losses": 0,
      "win_rate": 100,
      "is_permaban": false
    },
    {
      "team_id": 631,
      "map_name": "de_mirage",
      "matches_played": 5,
      "wins": 2,
      "losses": 3,
      "win_rate": 40,
      "is_permaban": false
    },
    {
      "team_id": 631,
      "map_name": "de_ancient",
      "matches_played": 4,
      "wins": 0,
      "losses": 4,
      "win_rate": 0,
      "is_permaban": false
    }
  ]
}

This endpoint retrieves map pool statistics for a specific team, showing their performance on each CS2 map.

HTTP Request

GET https://api.balldontlie.io/cs/v1/team_map_pool

Query Parameters

Parameter	Type	Required	Description
team_id	number	Yes	The ID of the team

Rankings

Get Current Rankings

curl "https://api.balldontlie.io/cs/v1/rankings" \
  -H "Authorization: YOUR_API_KEY"

fetch("https://api.balldontlie.io/cs/v1/rankings", {
  headers: {
    Authorization: "YOUR_API_KEY",
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data));

import requests

response = requests.get(
    "https://api.balldontlie.io/cs/v1/rankings",
    headers={"Authorization": "YOUR_API_KEY"}
)

data = response.json()

{
  "data": [
    {
      "rank": 1,
      "points": 1987.71,
      "ranking_type": "bo3",
      "ranking_date": "2026-01-02",
      "team": {
        "id": 631,
        "name": "FURIA",
        "short_name": "FURIA"
      }
    },
    {
      "rank": 2,
      "points": 1971.41,
      "ranking_type": "bo3",
      "ranking_date": "2026-01-02",
      "team": {
        "id": 650,
        "name": "Vitality",
        "short_name": "VIT"
      }
    },
    {
      "rank": 3,
      "points": 1884.9,
      "ranking_type": "bo3",
      "ranking_date": "2026-01-02",
      "team": {
        "id": 2018,
        "name": "Falcons",
        "short_name": "FLC"
      }
    }
  ]
}

This endpoint retrieves the current official CS2 team rankings.

HTTP Request

GET https://api.balldontlie.io/cs/v1/rankings

Matches

Get All Matches

curl "https://api.balldontlie.io/cs/v1/matches?per_page=25" \
  -H "Authorization: YOUR_API_KEY"

fetch("https://api.balldontlie.io/cs/v1/matches?per_page=25", {
  headers: {
    Authorization: "YOUR_API_KEY",
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data));

import requests

response = requests.get(
    "https://api.balldontlie.io/cs/v1/matches",
    headers={"Authorization": "YOUR_API_KEY"},
    params={"per_page": 25}
)

data = response.json()

{
  "data": [
    {
      "id": 67356,
      "slug": "vitality-vs-faze-starladder-budapest-major-2025",
      "tournament": {
        "id": 2092,
        "name": "StarLadder Budapest Major 2025",
        "slug": "starladder-budapest-major-2025",
        "tier": "s",
        "start_date": "2025-12-04",
        "end_date": "2025-12-14",
        "prize_pool": 1170000,
        "prize_pool_currency": "USD",
        "location": null,
        "country": null,
        "is_online": false,
        "status": "finished"
      },
      "stage": {
        "id": 4521,
        "name": "Grand Final",
        "stage_type": "bracket",
        "stage_order": 3,
        "best_of": 5,
        "rounds_count": 1,
        "start_date": "2025-12-14",
        "end_date": "2025-12-14",
        "status": "finished"
      },
      "team1": {
        "id": 650,
        "name": "Vitality",
        "short_name": "VIT"
      },
      "team2": {
        "id": 769,
        "name": "FaZe",
        "short_name": "FaZe"
      },
      "team1_score": 3,
      "team2_score": 1,
      "winner": {
        "id": 650,
        "name": "Vitality",
        "short_name": "VIT"
      },
      "best_of": 5,
      "status": "finished",
      "start_time": "2025-12-14T14:00:00Z",
      "end_time": "2025-12-14T18:30:00Z"
    }
  ],
  "meta": {
    "next_cursor": 67357,
    "per_page": 25
  }
}

This endpoint retrieves all CS2 matches with optional filtering.

HTTP Request

GET https://api.balldontlie.io/cs/v1/matches

Query Parameters

Parameter	Type	Required	Description
cursor	number	No	Pagination cursor from previous response
per_page	number	No	Number of results per page (max: 100)
team_ids	number[]	No	Filter by team IDs (array)
tournament_ids	number[]	No	Filter by tournament IDs (array)
dates	string[]	No	Filter by dates (YYYY-MM-DD format, array)

Get a Specific Match

curl "https://api.balldontlie.io/cs/v1/matches/67356" \
  -H "Authorization: YOUR_API_KEY"

fetch("https://api.balldontlie.io/cs/v1/matches/67356", {
  headers: {
    Authorization: "YOUR_API_KEY",
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data));

import requests

response = requests.get(
    "https://api.balldontlie.io/cs/v1/matches/67356",
    headers={"Authorization": "YOUR_API_KEY"}
)

data = response.json()

{
  "data": {
    "id": 67356,
    "slug": "vitality-vs-faze-starladder-budapest-major-2025",
    "tournament": {
      "id": 2092,
      "name": "StarLadder Budapest Major 2025",
      "slug": "starladder-budapest-major-2025",
      "tier": "s",
      "start_date": "2025-12-04",
      "end_date": "2025-12-14",
      "prize_pool": 1170000,
      "prize_pool_currency": "USD",
      "location": null,
      "country": null,
      "is_online": false,
      "status": "finished"
    },
    "stage": {
      "id": 4521,
      "name": "Grand Final",
      "stage_type": "bracket",
      "stage_order": 3,
      "best_of": 5,
      "rounds_count": 1,
      "start_date": "2025-12-14",
      "end_date": "2025-12-14",
      "status": "finished"
    },
    "team1": {
      "id": 650,
      "name": "Vitality",
      "short_name": "VIT"
    },
    "team2": {
      "id": 769,
      "name": "FaZe",
      "short_name": "FaZe"
    },
    "team1_score": 3,
    "team2_score": 1,
    "winner": {
      "id": 650,
      "name": "Vitality",
      "short_name": "VIT"
    },
    "best_of": 5,
    "status": "finished",
    "start_time": "2025-12-14T14:00:00Z",
    "end_time": "2025-12-14T18:30:00Z"
  }
}

This endpoint retrieves a specific match.

HTTP Request

GET https://api.balldontlie.io/cs/v1/matches/<ID>

URL Parameters

Parameter	Description
ID	The ID of the match

Match Maps

A match consists of one or more maps depending on the format. A Bo1 (best-of-1) match has 1 map, a Bo3 has up to 3 maps, and a Bo5 has up to 5 maps. Use the match_id field to associate maps with their parent match.

Get Match Maps

curl "https://api.balldontlie.io/cs/v1/match_maps?match_ids[]=67356" \
  -H "Authorization: YOUR_API_KEY"

fetch("https://api.balldontlie.io/cs/v1/match_maps?match_ids[]=67356", {
  headers: {
    Authorization: "YOUR_API_KEY",
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data));

import requests

response = requests.get(
    "https://api.balldontlie.io/cs/v1/match_maps",
    headers={"Authorization": "YOUR_API_KEY"},
    params={"match_ids[]": [67356]}
)

data = response.json()

{
  "data": [
    {
      "id": 201794,
      "match_id": 67356,
      "map_name": "de_nuke",
      "map_number": 1,
      "team1_score": 13,
      "team2_score": 5,
      "winner": {
        "id": 650,
        "name": "Vitality",
        "short_name": "VIT"
      },
      "duration_seconds": 2340,
      "overtime_rounds": null
    },
    {
      "id": 201795,
      "match_id": 67356,
      "map_name": "de_dust2",
      "map_number": 2,
      "team1_score": 8,
      "team2_score": 13,
      "winner": {
        "id": 769,
        "name": "FaZe",
        "short_name": "FaZe"
      },
      "duration_seconds": 2680,
      "overtime_rounds": null
    },
    {
      "id": 201796,
      "match_id": 67356,
      "map_name": "de_inferno",
      "map_number": 3,
      "team1_score": 13,
      "team2_score": 9,
      "winner": {
        "id": 650,
        "name": "Vitality",
        "short_name": "VIT"
      },
      "duration_seconds": 2920,
      "overtime_rounds": null
    },
    {
      "id": 201797,
      "match_id": 67356,
      "map_name": "de_ancient",
      "map_number": 4,
      "team1_score": 13,
      "team2_score": 7,
      "winner": {
        "id": 650,
        "name": "Vitality",
        "short_name": "VIT"
      },
      "duration_seconds": 2560,
      "overtime_rounds": null
    }
  ]
}

This endpoint retrieves all maps for specified matches.

HTTP Request

GET https://api.balldontlie.io/cs/v1/match_maps

Query Parameters

Parameter	Type	Required	Description
match_ids	number[]	Yes	Match IDs (array, required)

Match Map Stats

Get Match Map Statistics

curl "https://api.balldontlie.io/cs/v1/match_map_stats?match_map_id=201794" \
  -H "Authorization: YOUR_API_KEY"

fetch("https://api.balldontlie.io/cs/v1/match_map_stats?match_map_id=201794", {
  headers: {
    Authorization: "YOUR_API_KEY",
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data));

import requests

response = requests.get(
    "https://api.balldontlie.io/cs/v1/match_map_stats",
    headers={"Authorization": "YOUR_API_KEY"},
    params={"match_map_id": 201794}
)

data = response.json()

{
  "data": {
    "match_map_id": 201794,
    "map_name": "de_nuke",
    "rounds": [
      {
        "id": 1,
        "round_number": 1,
        "winner_side": "CT",
        "loser_side": "T",
        "end_reason": "Bomb defused",
        "duration_seconds": 95,
        "team_stats": [
          {
            "id": 1,
            "team": {
              "id": 650,
              "name": "Vitality",
              "short_name": "VIT"
            },
            "team_side": "CT",
            "won": true,
            "is_pistol_round": true,
            "kills": 5,
            "deaths": 3,
            "assists": 2,
            "headshots": 3,
            "first_kills": 1,
            "first_deaths": 0,
            "trade_kills": 1,
            "trade_deaths": 0,
            "damage": 500,
            "utility_value": 150,
            "equipment_value": 800,
            "money_spent": 800,
            "money_saved": 0,
            "loss_bonus_streak": 0,
            "win_streak": 1,
            "clutches": 0,
            "clutch_attempts": 0
          }
        ]
      }
    ]
  }
}

This endpoint retrieves detailed round-by-round statistics for a specific map in a match, including team performance metrics for each round.

HTTP Request

GET https://api.balldontlie.io/cs/v1/match_map_stats

Query Parameters

Parameter	Type	Required	Description
match_map_id	number	Yes	The ID of the match map

Player Match Stats

Get Player Match Statistics

curl "https://api.balldontlie.io/cs/v1/player_match_stats?match_id=67356" \
  -H "Authorization: YOUR_API_KEY"

fetch("https://api.balldontlie.io/cs/v1/player_match_stats?match_id=67356", {
  headers: {
    Authorization: "YOUR_API_KEY",
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data));

import requests

response = requests.get(
    "https://api.balldontlie.io/cs/v1/player_match_stats",
    headers={"Authorization": "YOUR_API_KEY"},
    params={"match_id": 67356}
)

data = response.json()

{
  "data": [
    {
      "player": {
        "id": 294,
        "nickname": "ZywOo"
      },
      "match_id": 67356,
      "team_id": 650,
      "kills": 78,
      "deaths": 42,
      "assists": 12,
      "adr": 92.4,
      "kast": 0.78,
      "rating": 1.32,
      "headshot_percentage": 52.5,
      "first_kills": 9,
      "first_deaths": 3,
      "clutches_won": 2
    },
    {
      "player": {
        "id": 512,
        "nickname": "apEX"
      },
      "match_id": 67356,
      "team_id": 650,
      "kills": 54,
      "deaths": 38,
      "assists": 18,
      "adr": 76.8,
      "kast": 0.82,
      "rating": 1.12,
      "headshot_percentage": 44.4,
      "first_kills": 5,
      "first_deaths": 4,
      "clutches_won": 1
    },
    {
      "player": {
        "id": 1847,
        "nickname": "ropz"
      },
      "match_id": 67356,
      "team_id": 769,
      "kills": 58,
      "deaths": 51,
      "assists": 8,
      "adr": 79.2,
      "kast": 0.71,
      "rating": 1.05,
      "headshot_percentage": 48.3,
      "first_kills": 6,
      "first_deaths": 5,
      "clutches_won": 1
    }
  ]
}

This endpoint retrieves player statistics aggregated across all maps in a match.

HTTP Request

GET https://api.balldontlie.io/cs/v1/player_match_stats

Query Parameters

Parameter	Type	Required	Description
match_id	number	Yes	The ID of the match

Player Match Map Stats

Get Player Match Map Statistics

curl "https://api.balldontlie.io/cs/v1/player_match_map_stats?match_map_id=201794" \
  -H "Authorization: YOUR_API_KEY"

fetch("https://api.balldontlie.io/cs/v1/player_match_map_stats?match_map_id=201794", {
  headers: {
    Authorization: "YOUR_API_KEY",
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data));

import requests

response = requests.get(
    "https://api.balldontlie.io/cs/v1/player_match_map_stats",
    headers={"Authorization": "YOUR_API_KEY"},
    params={"match_map_id": 201794}
)

data = response.json()

{
  "data": [
    {
      "player": {
        "id": 294,
        "nickname": "ZywOo"
      },
      "match_map_id": 201794,
      "kills": 21,
      "deaths": 8,
      "assists": 3,
      "adr": 98.4,
      "kast": 83.3,
      "rating": 1.58,
      "headshot_percentage": 57.1,
      "first_kills": 3,
      "first_deaths": 1,
      "clutches_won": 1
    },
    {
      "player": {
        "id": 512,
        "nickname": "apEX"
      },
      "match_map_id": 201794,
      "kills": 15,
      "deaths": 7,
      "assists": 5,
      "adr": 82.6,
      "kast": 88.9,
      "rating": 1.35,
      "headshot_percentage": 46.7,
      "first_kills": 2,
      "first_deaths": 0,
      "clutches_won": 0
    },
    {
      "player": {
        "id": 1847,
        "nickname": "ropz"
      },
      "match_map_id": 201794,
      "kills": 12,
      "deaths": 14,
      "assists": 2,
      "adr": 68.5,
      "kast": 66.7,
      "rating": 0.92,
      "headshot_percentage": 50.0,
      "first_kills": 1,
      "first_deaths": 2,
      "clutches_won": 0
    }
  ]
}

This endpoint retrieves player statistics for a specific map within a match.

HTTP Request

GET https://api.balldontlie.io/cs/v1/player_match_map_stats

Query Parameters

Parameter	Type	Required	Description
match_map_id	number	Yes	The ID of the match map

Player Accuracy Stats

Get Player Accuracy Statistics

curl "https://api.balldontlie.io/cs/v1/player_accuracy_stats?player_id=1" \
  -H "Authorization: YOUR_API_KEY"

fetch("https://api.balldontlie.io/cs/v1/player_accuracy_stats?player_id=1", {
  headers: {
    Authorization: "YOUR_API_KEY",
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data));

import requests

response = requests.get(
    "https://api.balldontlie.io/cs/v1/player_accuracy_stats",
    headers={"Authorization": "YOUR_API_KEY"},
    params={"player_id": 1}
)

data = response.json()

{
  "data": [
    {
      "player_id": 44,
      "hit_group": "Head",
      "hits_sum": 1578,
      "damage_sum": 101822,
      "kills_sum": 1202
    },
    {
      "player_id": 44,
      "hit_group": "Chest",
      "hits_sum": 4542,
      "damage_sum": 95885,
      "kills_sum": 703
    },
    {
      "player_id": 44,
      "hit_group": "Stomach",
      "hits_sum": 1442,
      "damage_sum": 35804,
      "kills_sum": 369
    },
    {
      "player_id": 44,
      "hit_group": "RightArm",
      "hits_sum": 688,
      "damage_sum": 14721,
      "kills_sum": 100
    },
    {
      "player_id": 44,
      "hit_group": "LeftLeg",
      "hits_sum": 223,
      "damage_sum": 4364,
      "kills_sum": 35
    }
  ]
}

This endpoint retrieves accuracy statistics for a specific player, broken down by hit groups (body parts).

HTTP Request

GET https://api.balldontlie.io/cs/v1/player_accuracy_stats

Query Parameters

Parameter	Type	Required	Description
player_id	number	Yes	The ID of the player

Error Codes

The BALLDONTLIE API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid
401	Unauthorized -- Your API key is wrong or you don't have access to this endpoint
404	Not Found -- The specified resource could not be found
429	Too Many Requests -- You're making too many requests! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.

Rate Limiting

Rate limits are enforced based on your account tier:

FREE: 5 requests per minute
ALL-STAR: 60 requests per minute
GOAT: 600 requests per minute

When you exceed the rate limit, you'll receive a 429 status code. The response will include headers indicating your current rate limit status:

X-RateLimit-Limit: Maximum requests per minute
X-RateLimit-Remaining: Remaining requests in current window
X-RateLimit-Reset: Unix timestamp when the rate limit resets