Getting started
This page will walk you through everything you need to know to get up and running with the API
1. How the data is structured
Before making your first request, it's worth understanding how PandaScore organises esports data. Everything flows from the top down:
League → Series → Tournament → Match → Game
- A League is the top-level competition (e.g. ESL Pro League).
- A Series is a single time-bound occurrence of that league (e.g. ESL Pro League Season 21).
- A Tournament is a stage within that series (e.g. Group Stage, Playoffs).
- A Match is a head-to-head between two teams within a tournament.
- A Game is a single map or game within that match (e.g. Map 1 of a best-of-3).
📖 Full breakdown: Fundamentals
2. Authentication
All API requests require your token, passed as a query parameter:
https://api.pandascore.co/matches/upcoming?token=YOUR_TOKENYou can find your token in your PandaScore dashboard.
📖 Full details: Authentication | Rate & connection limits
3. Key concepts to know before you build
These three topics come up in almost every integration. Read them before you start polling:
Match lifecycle & the complete field
complete fieldMatches move through several statuses (not_started → running → finished). For matches with detailed statistics, there's an additional field you need to know about: complete.
complete = falseafter a game finishes means post-game statistics are still being processed. Do not consume stats yet.complete = truemeans statistics are finalised and ready to use.
📖 Match lifecycle | Match formats
Coverage levels: detailed_stats and live_supported
detailed_stats and live_supportedNot every tournament has the same level of coverage. Two fields tell you exactly what to expect:
| Field | Value | What it means |
|---|---|---|
detailed_stats | false | Fixtures and results only — no post-game statistics |
detailed_stats | true | Full post-game statistics will be available |
live_supported | true | In-game live data is available for this tournament's matches |
Use these as filters to fetch tournaments relevant to your use case. For example, to get only live-supported upcoming tournaments:
GET /tournaments/upcoming?filter[live_supported]=trueOr to only get matches that will have statistics:
GET /matches/upcoming?filter[detailed_stats]=true📖 Filtering and sorting | Tournaments in-depth
Pagination
API responses are paginated by default (50 results per page). Use page and per_page parameters to navigate:
GET /matches/upcoming?page=2&per_page=100per_page maximum is 100.
4. Fixtures & schedule endpoints
These endpoints are available on all plans and form the backbone of any integration.
Matches
| What you need | Endpoint |
|---|---|
| Upcoming matches | GET /matches/upcoming |
| Live / running matches | GET /matches/running |
| Past matches | GET /matches/past |
| A specific match | GET /matches/{id} |
| Match opponents | GET /matches/{id}/opponents |
Tournaments, leagues & series
| What you need | Endpoint |
|---|---|
| Upcoming tournaments | GET /tournaments/upcoming |
| Tournament standings | GET /tournaments/{id}/standings |
| Tournament brackets | GET /tournaments/{id}/brackets |
| Tournament rosters | GET /tournaments/{id}/rosters |
| Matches in a tournament | GET /tournaments/{id}/matches |
| List all leagues | GET /leagues |
| Matches in a league | GET /leagues/{id}/matches |
| List all series | GET /series |
Players & teams
| What you need | Endpoint |
|---|---|
| A specific player | GET /players/{id} |
| A specific team | GET /teams/{id} |
| A player's match history | GET /players/{id}/matches |
| A player's tournament history | GET /players/{id}/tournaments |
| A team's match history | GET /teams/{id}/matches |
| A team's series history | GET /teams/{id}/series |
Tip: To trace a player's team history across their career, useGET /players/{id}/tournaments— this returns the team they played for in each tournament, which is the most reliable way to track roster changes.
📖 API Reference — Players | Teams
Currently live matches (WebSocket)
| What you need | Endpoint |
|---|---|
| All currently open live WebSocket streams | GET /lives |
This endpoint lists all matches currently streaming live data, including the WebSocket URLs for frames and events. WebSocket connections open 15 minutes before the scheduled match start time.
📖 API Reference — Lives | WebSockets overview
5. Keeping your data in sync
If you're building a database or pipeline, you don't need to re-poll every endpoint to catch updates. The incidents feed gives you a stream of all changes, additions, and deletions across the API — think of it like a changelog you can poll regularly.
| What you need | Endpoint |
|---|---|
| All recent changes, additions & deletions | GET /incidents |
| Only new additions | GET /additions |
| Only updated objects | GET /changes |
| Only deleted objects | GET /deletions |
This covers everything: match reschedules, roster changes, score corrections, tournament updates. Available on all plans.
📖 API Reference — Incidents | Tracking changes
6. CS2 endpoint naming
One thing that trips up almost every CS2 integration: all CS2 endpoints use the /csgo/ prefix, not /cs2/. This is for legacy reasons and applies across the board:
GET /csgo/matches/upcoming
GET /csgo/games/{id}
GET /csgo/players/{id}/stats📖 Counter-Strike 2 migration guide
7. Testing with the Sandbox
If you're on the Pro Live plan, you don't need to wait for a live match to test your WebSocket integration. The sandbox lets you replay a CS or LoL game on demand at adjustable speeds.
Start a LoL replay:
POST https://live.pandascore.co/api/lol/replayStart a CS replay:
POST https://live.pandascore.co/api/csgo/replayBoth return WebSocket URLs for frames and events. You can control playback_speed (1×, 1.5×, 2×) and set a starting point in-game (ingame_timestamp for LoL, round_number for CS).
8. Frequently asked questions
Browse common integration questions, including:
- When will post-game stats be available after a match?
- What is a game advantage?
- Why am I getting a CORS error?
- How do I find player team history?
📖 FAQ
10. Get support
The fastest way to get help is to join our Slack community. Once you're in, we'll set up a private channel for you and your team — it's the best place to ask API questions, flag data issues, and give feedback.
What's next?
Head to the Game Data Reference to see exactly which endpoints are available on your plan for Counter-Strike, League of Legends, Dota 2, and Valorant.
Updated 2 days ago