HLTV APIhltv.org ↗
Access HLTV.org CS esports data via API: match results, team/player stats, world rankings, upcoming matches, and fantasy league data across 9 endpoints.
What is the HLTV API?
The HLTV.org API provides access to Counter-Strike esports data across 9 endpoints, covering match results, player and team statistics, world rankings, upcoming match schedules, and fantasy league information. The get_match_details endpoint, for example, returns per-map scores alongside per-player ADR, K/D, and rating for every completed match. All data reflects the live HLTV.org rankings and result pages.
curl -X GET 'https://api.parse.bot/scraper/b3500f47-4f4d-4f28-b85d-7e73293b70d1/get_results?limit=10' \ -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 hltv-org-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.
"""HLTV.org SDK — browse CS esports data: results, rankings, stats, fantasy."""
from parse_apis.hltv_org_api import Hltv, MatchNotFound
client = Hltv()
# Recent match results — limit caps total items fetched.
for result in client.matchsummaries.list(limit=3):
print(result.team1, result.score, result.team2, "|", result.event)
# Drill into the first result's full match details.
result = client.matchsummaries.list(limit=1).first()
if result:
try:
match = result.details()
print(match.match_id, match.teams)
for m in match.maps:
print(f" {m.name}: {m.score}")
except MatchNotFound as exc:
print(f"Match gone: {exc.match_id}")
# World team rankings — top 5.
for ranking in client.teamrankings.list(limit=5):
print(ranking.rank, ranking.team, ranking.points)
# Player stats over the last 30 days.
for player in client.playerstats.list(days=30, limit=3):
print(player.name, player.team, player.rating)
# Fantasy: get season overview, then fetch leaderboard for the first event.
season = client.fantasyseasons.overview()
print(season.season_name, season.season_finished)
if season.events:
event = season.events[0]
lb = event.leaderboard()
print(lb.event_name, lb.total_teams)
for entry in lb.leaderboard[:3]:
print(f" #{entry.rank} {entry.user} — {entry.total_points} pts")
print("exercised: matchsummaries.list / details / teamrankings.list / playerstats.list / fantasyseasons.overview / event.leaderboard")
Fetch recent match results from HLTV in reverse chronological order. Each result includes the two teams, final score, event name, and a direct URL. No server-side pagination; limit caps the number of items returned from the single results page.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of results to return. |
{
"type": "object",
"fields": {
"results": "array of match result objects with match_id, date, team1, team2, score, event, url"
},
"sample": {
"data": {
"results": [
{
"url": "https://www.hltv.org/matches/2395078/wingman-vs-eternal-premium-esea-advanced-season-57-europe",
"date": "Results for June 10th 2026",
"event": "ESEA Advanced Season 57 Europe",
"score": "2 - 1",
"team1": "Wingman",
"team2": "eternal premium",
"match_id": "2395078"
}
]
},
"status": "success"
}
}About the HLTV API
Match Results and Schedules
The get_results endpoint returns recent completed matches in reverse chronological order. Each result object includes match_id, date, team1, team2, score, event, and a direct url. A limit parameter caps the number of results returned. For upcoming fixtures, get_upcoming_matches returns all scheduled and live matches with status, date, time, and event fields. It accepts a filter_cct boolean to restrict results to CCT-series tournaments only.
Player and Team Statistics
get_player_stats and get_team_stats both accept a days integer that defines a lookback window from today. Player objects include player_id, name, team, maps, rounds, kd_diff, kd, and rating, sorted by rating descending. Team objects mirror this structure with team_id, name, maps, kd_diff, kd, and rating. get_match_details goes deeper: for a given match_id it returns maps (name and score per map), a stats array of per-player kd, adr, and rating rows, and the two team names. The endpoint falls back to the main match page when the stats sub-page is unavailable.
Rankings and Tournaments
get_team_rankings returns all ranked teams with rank, team name, and points from HLTV's weekly world rankings — no input parameters required. get_cct_tournaments lists current and upcoming CCT-series events with name, url, and date. These two endpoints are useful for building ranking trackers or tournament calendars without additional filtering logic on your side.
Fantasy League Data
get_fantasy_info returns the active season name, a season_finished flag, and an events array where each entry carries fantasy_id, name, month, state (finished/live/upcoming), winner, enabled, description, and the list of participating teams. Pass a fantasy_id from that response into get_fantasy_leaderboard to retrieve the top-10 public league standings, including rank, user, team_name, total_points, and a breakdown into role_points, boost_points, player_points, and team_points.
The HLTV API is a managed, monitored endpoint for hltv.org — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when hltv.org 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 hltv.org 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?+
- Build a live CS match tracker that polls
get_upcoming_matchesand surfaces live match status with event name and team names. - Generate weekly team performance reports using
get_team_statswith a 7-day window and thekd_diffandratingfields. - Power a world-rankings widget by reading
rank, team name, andpointsfromget_team_rankings. - Display detailed post-match breakdowns by fetching
get_match_detailsfor amatch_idand rendering per-player ADR and rating by map. - Build a fantasy CS assistant that reads
get_fantasy_infofor team rosters and event states, then checksget_fantasy_leaderboardfor point breakdowns. - Filter and display only CCT tournament fixtures by calling
get_upcoming_matcheswithfilter_cct: true. - Track player rating trends over time by calling
get_player_statswith differentdaysvalues and comparing the sortedratingfield.
| 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 HLTV.org have an official developer API?+
What does `get_match_details` return, and what happens when stats are unavailable?+
get_match_details takes a numeric match_id string and returns the two team names, an array of map objects (each with name and score), and a stats array of per-player rows covering kd, adr, and rating. When the dedicated stats sub-page for a match is unavailable, the endpoint falls back to the main match page, which may return partial data.How current are the team rankings from `get_team_rankings`?+
get_team_rankings reflects whatever ranking is currently published on the HLTV rankings page. Intra-week changes are not reflected until the next HLTV update cycle.Does the API cover individual player profiles, match histories per player, or head-to-head records?+
get_player_stats and per-match player performance via get_match_details, but individual player profile pages, career match histories, and head-to-head records are not exposed. You can fork this API on Parse and revise it to add an endpoint targeting those data surfaces.Does `get_results` support pagination to retrieve older historical results?+
get_results reads from a single results page and the limit parameter caps how many items from that page are returned. Results older than what appears on that page are not accessible through this endpoint. You can fork the API on Parse and revise it to target HLTV's paginated results archive if you need deeper history.