CS2 Matches API

Complete reference for CS2 series and match endpoints, SDK methods, params, and response shapes

Overview

The CS2 Matches API gives you access to series (e.g. BO3) and individual maps (matches): list and get series, list and get maps, and full statistics per map. We distinguish between Series (a set of maps) and Matches (single maps).

For full analytics for one map (weapon stats, utility stats, team stats, top performers), use Match Statistics API (getStats()).

Scope

All endpoints are organization-scoped. You only see data from servers owned by your organization.

Base route

Base path	Description
`/v1/cs2`	All CS2 series and match endpoints

Series

listSeries()

List CS2 series with optional filters and pagination.

HTTP API

Method	Path	Description
`GET`	`/v1/cs2/series`	List series

Query parameters

Parameter	Type	Required	Description
`page`	`number`	No	Page number (1-indexed). Default `1`.
`pageSize`	`number`	No	Items per page. Default `20`, max `100`.
`status`	`string`	No	Filter: `live`, `finished`, `upcoming`, `cancelled`.
`serverId`	`string`	No	Filter by server ID.
`dateFrom`	`string`	No	Start date (ISO 8601).
`dateTo`	`string`	No	End date (ISO 8601).

Headers: Authorization: Bearer <your-api-key>

Example (cURL)

curl -X GET "https://api.sweathost.com/v1/cs2/series?status=finished&page=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

SDK

Parameters

Parameter	Type	Required	Description
`params`	`MatchFilters`	No	Filters and pagination (see query params above).
`options`	`RequestOptions`	No	Optional request config.

Return type: Promise<ListSeriesResponse>

Example

const allSeries = await client.matches.listSeries();
const finished = await client.matches.listSeries({
  status: 'finished',
  page: 1,
  pageSize: 10,
});

Response structure

ListSeriesResponse: { page, pageSize, total, items }. Each item is ListSeriesItem:

Field	Type	Description
`id`	`string`	Unique series ID.
`seriesId`	`string`	External series ID.
`serverId`	`string`	Server ID.
`serverName`	`string`	Server name.
`format`	`string`	e.g. `bo1`, `bo3`, `bo5`.
`team1Name`	`string`	Team 1 name.
`team2Name`	`string`	Team 2 name.
`team1MapsWon`	`number`	Maps won by team 1.
`team2MapsWon`	`number`	Maps won by team 2.
`status`	`string`	e.g. `live`, `finished`.
`currentMapIndex`	`number`	Current map index.
`mapPool`	`string[]`	Map pool.
`gameMode`	`string`	Game mode.
`startedAt`	`string`	ISO 8601.
`finishedAt`	`string \| null`	ISO 8601.
`duration`	`number \| null`	Duration in seconds.
`winnerTeam`	`string \| null`	Winner team name.
`maps`	`array`	Optional list of `{ id, mapNumber, mapName, status }`.

getSeries()

Get one series by ID, including all maps.

HTTP API

Method	Path	Description
`GET`	`/v1/cs2/series/:seriesId`	Get series by ID

Path parameters

Parameter	Type	Required	Description
`seriesId`	`string`	Yes	Series ID (e.g. from list).

Headers: Authorization: Bearer <your-api-key>

Example (cURL)

curl -X GET "https://api.sweathost.com/v1/cs2/series/SERIES_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

SDK

Parameters

Parameter	Type	Required	Description
`seriesId`	`string`	Yes	Series ID.
`options`	`RequestOptions`	No	Optional request config.

Return type: Promise<Cs2SeriesDetail>

Example

const series = await client.matches.getSeries('SERIES-2026-001');
console.log(`${series.team1Name} vs ${series.team2Name}`);
series.maps.forEach(map => {
  console.log(`  Map ${map.mapNumber}: ${map.mapName} (${map.team1RoundScore}-${map.team2RoundScore})`);
});

Cs2SeriesDetail extends ListSeriesItem and includes full maps array with round scores, status, and player counts.

Matches (maps)

list()

List individual maps across all series.

HTTP API

Method	Path	Description
`GET`	`/v1/cs2/matches`	List matches (maps)

Query parameters

Parameter	Type	Required	Description
`page`	`number`	No	Page number (1-indexed). Default `1`.
`pageSize`	`number`	No	Items per page. Default `20`, max `100`.
`limit`	`number`	No	Alias for page size.
`map`	`string`	No	Filter by map name (e.g. `de_dust2`).
`status`	`string`	No	Filter by status.
`serverId`	`string`	No	Filter by server ID.
`dateFrom`	`string`	No	Start date (ISO 8601).
`dateTo`	`string`	No	End date (ISO 8601).

Headers: Authorization: Bearer <your-api-key>

Example (cURL)

curl -X GET "https://api.sweathost.com/v1/cs2/matches?map=de_dust2" \
  -H "Authorization: Bearer YOUR_API_KEY"

SDK

Parameters

Parameter	Type	Required	Description
`params`	`MatchFilters`	No	Filters and pagination (includes `map`).
`options`	`RequestOptions`	No	Optional request config.

Return type: Promise<ListMatchesResponse>

Example

const dust2Matches = await client.matches.list({ map: 'de_dust2' });

Response structure

ListMatchesResponse: { page, pageSize, total, items }. Each item is ListMatchItem:

Field	Type	Description
`id`	`string`	Unique map (match) ID. Use for `get()` and `getStats()`.
`serverId`	`string`	Server ID.
`serverName`	`string`	Server name.
`matchId`	`string \| null`	Legacy/external match reference.
`map`	`string`	Map name (e.g. `de_dust2`).
`gameMode`	`string`	Game mode.
`team1Name`	`string \| null`	Team 1 name.
`team2Name`	`string \| null`	Team 2 name.
`team1Score`	`number`	Team 1 round score.
`team2Score`	`number`	Team 2 round score.
`status`	`string`	e.g. `finished`, `live`.
`startedAt`	`string`	ISO 8601.
`finishedAt`	`string \| null`	ISO 8601.
`duration`	`number \| null`	Duration in seconds.
`playerCount`	`number`	Player count.

get()

Get one map (match) by ID with full details and player stats.

HTTP API

Method	Path	Description
`GET`	`/v1/cs2/matches/:mapId`	Get match by map ID

Path parameters

Parameter	Type	Required	Description
`mapId`	`string`	Yes	Map (match) ID — same as `id` from list.

Headers: Authorization: Bearer <your-api-key>

Example (cURL)

curl -X GET "https://api.sweathost.com/v1/cs2/matches/MAP_UUID" \
  -H "Authorization: Bearer YOUR_API_KEY"

SDK

Parameters

Parameter	Type	Required	Description
`matchId`	`string`	Yes	Map (match) ID.
`options`	`RequestOptions`	No	Optional request config.

Return type: Promise<Cs2MatchDetail>

Example

const match = await client.matches.get('map-uuid-123');
console.log(`${match.map}: ${match.team1Score}-${match.team2Score}`);

Response structure

Cs2MatchDetail: match metadata plus players: Cs2PlayerWithStats[] (with optional weaponStats, utilityStats). Includes server, id, map, team1Name, team2Name, team1Score, team2Score, status, startedAt, finishedAt, duration.

getStats()

Get full statistics for one map (weapon stats, utility stats, team stats, top performers). Full request/response and all fields: Match Statistics API.

HTTP API

Method	Path	Description
`GET`	`/v1/cs2/matches/:mapId/stats`	Get map statistics

Path parameters: mapId (string, required).

SDK

Parameters

Parameter	Type	Required	Description
`matchId`	`string`	Yes	Map (match) ID.
`options`	`RequestOptions`	No	Optional request config.

Return type: Promise<MatchStats>

Example

const stats = await client.matches.getStats('map-uuid-123');
console.log(stats.overview.totalKills);
console.log(stats.topPerformers.topKiller.name);

Errors

HTTP	Code	Description
401	`UNAUTHORIZED`	Invalid or missing API key.
403	`FORBIDDEN`	Resource belongs to another organization.
404	`NOT_FOUND`	Series or match not found.

Ensure your API key has the servers:read scope for CS2 endpoints.

CS2 Matches API

On this page