Docs menu

BO3 API endpoint

BO3.gg esports match history API

Returns BO3.gg's esports match history for one game, newest first by default, with paging and filters: `status` (`finished`, `defwin`, `upcoming`, `current`, `canceled`, `postponed`; the default is finished and default-win matches together), `tier` (`s` to `d`), an inclusive `from`/`to` day range (UTC), `sort` and `offset`/`limit` (up to 100 per page). Each match has teams, scores, winner, best-of, tournament, maps and the site's AI prediction; `total` and `has_more` page through the full history.

GETapiKey1 credit/requestBO3/bo3/match-history

Endpoint facts

Method: GET
API path: /bo3/match-history
Auth: apiKey
Credits: 1 credit/request
Charged on: Successful 2xx responses only
Platform: BO3

BO3.gg Esports Data API Try BO3.gg esports match history API in Playground BO3 API documentation

How this endpoint behaves

Header: x-api-key required.

Parameters:

game: optional; allowed values: cs2, valorant, lol, dota2, r6siege, mlbb. Defaults to cs2.
status: optional; allowed values: finished, defwin, upcoming, current, canceled, postponed. Empty means finished and defwin together.
tier: optional; allowed values: s, a, b, c, d (s is the top tier).
from, to: optional days as YYYY-MM-DD (UTC), both inclusive.
sort: optional; allowed values: newest, oldest. Defaults to newest.
offset: optional zero-based offset; limit: optional page size, 1 to 100, default 20.

Notable response behavior:

total is the number of matches that fit the filters (for example more than 76,000 finished CS2 matches) and has_more says whether another page exists; step offset by limit to page.
Match status is one of upcoming, current (live), finished, defwin (default win), canceled or postponed; tier is s, a, b, c or d; each map status is upcoming, current or finished.
An invalid tier, status, game, date or page size returns 400; the upstream treats an unknown tier as an empty list, so the service rejects it instead. The response is cached for up to two minutes.

Sampled response

Request, 29 Oct 2026: GET /bo3/match-history?game=cs2&limit=40
Items in matches: 40
Fields filled in every checked item: 13
Fields empty in some or all items: 2

Field	Filled in, of 40 checked	Values in the sample
id	40
slug	40
url	40	bo3.gg
game	40	cs2 in all 40
status	40	finished (31), defwin (9)
best_of	40	1 to 3, median 3
tier	40	c (24), b (10), a (3) and 1 more
start_time	40	2026-10-29 to 2026-11-09
end_time	40	2026-10-29 to 2026-11-09
stars	40	0 to 4, median 0
live_coverage	40	true in 3 of 40
teams	40	median 2 entries
tournament	40
prediction	38
maps	32	median 2 entries

Request parameters

Parameter	Type	Required	Default	Description	Example
x-api-key (header)	string	Yes		API key required
game	string	No	cs2	Game; one of cs2, valorant, lol, dota2, r6siege, mlbb; defaults to cs2 Allowed values: cs2, valorant, lol, dota2, r6siege, mlbb.
status	string	No	finished and defwin together	Match status; one of finished, defwin, upcoming, current, canceled, postponed; defaults to finished and defwin together Allowed values: finished, defwin, upcoming, current, canceled, postponed.
tier	string	No		Tournament tier; one of s, a, b, c, d Allowed values: s, a, b, c, d.
from	string	No		First start day, YYYY-MM-DD (UTC, inclusive)	2026-10-01
to	string	No		Last start day, YYYY-MM-DD (UTC, inclusive)	2026-10-27
sort	string	No	newest	Order by start time; one of newest, oldest; defaults to newest Allowed values: newest, oldest.
offset	integer	No	0	Zero-based offset; defaults to 0 Minimum: 0.
limit	integer	No	20	Page size, 1 to 100; defaults to 20 Minimum: 1. Maximum: 100.

cURL example

curl -X GET "https://api.crawlora.net/api/v1/bo3/match-history?game=cs2&status=finished&tier=s&sort=newest&limit=10" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "source_url": "https://api.bo3.gg/api/v1/match-history",
    "fetched_at": "2026-10-28T10:00:00Z",
    "game": "cs2",
    "status": "finished,defwin",
    "total": 76604,
    "offset": 0,
    "limit": 20,
    "count": 1,
    "has_more": true,
    "matches": [
      {
        "id": 132243,
        "slug": "vitality-vs-natus-vincere-27-10-2026",
        "url": "https://bo3.gg/matches/vitality-vs-natus-vincere-27-10-2026",
        "game": "cs2",
        "status": "finished",
        "best_of": 3,
        "tier": "s",
        "start_time": "2026-10-27T17:55:00Z",
        "teams": [
          {
            "id": 667,
            "slug": "vitality",
            "name": "Vitality",
            "score": 2,
            "winner": true
          },
          {
            "id": 787,
            "slug": "natus-vincere",
            "name": "Natus Vincere",
            "score": 0,
            "winner": false
          }
        ],
        "tournament": {
          "id": 5338,
          "slug": "pgl-masters-bucharest-2026",
          "name": "PGL Masters Bucharest 2026",
          "tier": "s"
        }
      }
    ]
  }
}

Request schema

No body schema

Response schema

Inline response schema

Field	Type	Required	Enum	Example	Description
code	integer	No			Code is the HTTP status code or a custom code used to indicate the result of the request @example 200
data	bo3.MatchHistoryResponse	No
data.count	integer	No		20
data.fetched_at	string	No		2026-10-28T10:00:00Z
data.game	string	No		cs2
data.has_more	boolean	No		true
data.limit	integer	No		20
data.matches	array	No
data.matches[].best_of	integer	No		3
data.matches[].end_time	string	No
data.matches[].game	string	No		cs2
data.matches[].id	integer	No		132241
data.matches[].live_coverage	boolean	No		true
data.matches[].maps	array	No			MapRow record, 8 fields: begin_at, loser_score, map, number, status, winner_score, winner_team_id, winner_team_name. Described under BO3.gg match detail API.
data.matches[].prediction	bo3.Prediction	No
data.matches[].prediction.team1_score	integer	No		2
data.matches[].prediction.team2_score	integer	No		1
data.matches[].prediction.winner_team_id	integer	No		654
data.matches[].slug	string	No		spirit-vs-mouz-cs2-27-10-2026
data.matches[].stars	integer	No		4
data.matches[].start_time	string	No		2026-10-27T14:35:00Z
data.matches[].status	string	No	upcoming, current, finished, defwin, canceled, postponed	current
data.matches[].teams	array	No			Team record, 9 fields: country, country_code, id, logo_url, name, rank, score, slug, winner. Described under BO3.gg match detail API.
data.matches[].tier	string	No	s, a, b, c, d	s
data.matches[].tournament	bo3.TournamentRef	No			TournamentRef record, 5 fields: id, name, prize_usd, slug, tier. Described under BO3.gg match detail API.
data.matches[].url	string	No
data.offset	integer	No		0
data.source_url	string	No		https://bo3.gg/matches/current
data.status	string	No		finished,defwin
data.total	integer	No		76604
msg	unknown	No			Msg is the message that describes the result of the request @example "Request successful"

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
404	Not Found	#/definitions/app.Response
429	Too Many Requests	#/definitions/app.Response
503	Service Unavailable	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/bo3/match-history?game=cs2&status=finished&tier=s&sort=newest&limit=10" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

More BO3 endpoint docs BO3.gg Esports Data API BO3.gg CS2 economy baseline API documentation BO3.gg forum categories API documentation BO3.gg forum threads API documentation BO3.gg match maps and rounds API documentation BO3.gg per-player match statistics API documentation BO3.gg match detail API documentation

Open in Playground Back to group

Docs menu

BO3 API endpoint

BO3.gg esports match history API

GETapiKey1 credit/requestBO3/bo3/match-history

Endpoint facts

Method: GET
API path: /bo3/match-history
Auth: apiKey
Credits: 1 credit/request
Charged on: Successful 2xx responses only
Platform: BO3

BO3.gg Esports Data API Try BO3.gg esports match history API in Playground BO3 API documentation

How this endpoint behaves

Header: x-api-key required.

Parameters:

game: optional; allowed values: cs2, valorant, lol, dota2, r6siege, mlbb. Defaults to cs2.
status: optional; allowed values: finished, defwin, upcoming, current, canceled, postponed. Empty means finished and defwin together.
tier: optional; allowed values: s, a, b, c, d (s is the top tier).
from, to: optional days as YYYY-MM-DD (UTC), both inclusive.
sort: optional; allowed values: newest, oldest. Defaults to newest.
offset: optional zero-based offset; limit: optional page size, 1 to 100, default 20.

Notable response behavior:

total is the number of matches that fit the filters (for example more than 76,000 finished CS2 matches) and has_more says whether another page exists; step offset by limit to page.
Match status is one of upcoming, current (live), finished, defwin (default win), canceled or postponed; tier is s, a, b, c or d; each map status is upcoming, current or finished.
An invalid tier, status, game, date or page size returns 400; the upstream treats an unknown tier as an empty list, so the service rejects it instead. The response is cached for up to two minutes.

Sampled response

Request, 29 Oct 2026: GET /bo3/match-history?game=cs2&limit=40
Items in matches: 40
Fields filled in every checked item: 13
Fields empty in some or all items: 2

Field	Filled in, of 40 checked	Values in the sample
id	40
slug	40
url	40	bo3.gg
game	40	cs2 in all 40
status	40	finished (31), defwin (9)
best_of	40	1 to 3, median 3
tier	40	c (24), b (10), a (3) and 1 more
start_time	40	2026-10-29 to 2026-11-09
end_time	40	2026-10-29 to 2026-11-09
stars	40	0 to 4, median 0
live_coverage	40	true in 3 of 40
teams	40	median 2 entries
tournament	40
prediction	38
maps	32	median 2 entries

Request parameters

Parameter	Type	Required	Default	Description	Example
x-api-key (header)	string	Yes		API key required
game	string	No	cs2	Game; one of cs2, valorant, lol, dota2, r6siege, mlbb; defaults to cs2 Allowed values: cs2, valorant, lol, dota2, r6siege, mlbb.
status	string	No	finished and defwin together	Match status; one of finished, defwin, upcoming, current, canceled, postponed; defaults to finished and defwin together Allowed values: finished, defwin, upcoming, current, canceled, postponed.
tier	string	No		Tournament tier; one of s, a, b, c, d Allowed values: s, a, b, c, d.
from	string	No		First start day, YYYY-MM-DD (UTC, inclusive)	2026-10-01
to	string	No		Last start day, YYYY-MM-DD (UTC, inclusive)	2026-10-27
sort	string	No	newest	Order by start time; one of newest, oldest; defaults to newest Allowed values: newest, oldest.
offset	integer	No	0	Zero-based offset; defaults to 0 Minimum: 0.
limit	integer	No	20	Page size, 1 to 100; defaults to 20 Minimum: 1. Maximum: 100.

cURL example

curl -X GET "https://api.crawlora.net/api/v1/bo3/match-history?game=cs2&status=finished&tier=s&sort=newest&limit=10" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "source_url": "https://api.bo3.gg/api/v1/match-history",
    "fetched_at": "2026-10-28T10:00:00Z",
    "game": "cs2",
    "status": "finished,defwin",
    "total": 76604,
    "offset": 0,
    "limit": 20,
    "count": 1,
    "has_more": true,
    "matches": [
      {
        "id": 132243,
        "slug": "vitality-vs-natus-vincere-27-10-2026",
        "url": "https://bo3.gg/matches/vitality-vs-natus-vincere-27-10-2026",
        "game": "cs2",
        "status": "finished",
        "best_of": 3,
        "tier": "s",
        "start_time": "2026-10-27T17:55:00Z",
        "teams": [
          {
            "id": 667,
            "slug": "vitality",
            "name": "Vitality",
            "score": 2,
            "winner": true
          },
          {
            "id": 787,
            "slug": "natus-vincere",
            "name": "Natus Vincere",
            "score": 0,
            "winner": false
          }
        ],
        "tournament": {
          "id": 5338,
          "slug": "pgl-masters-bucharest-2026",
          "name": "PGL Masters Bucharest 2026",
          "tier": "s"
        }
      }
    ]
  }
}

Request schema

No body schema

Response schema

Inline response schema

Field	Type	Required	Enum	Example	Description
code	integer	No			Code is the HTTP status code or a custom code used to indicate the result of the request @example 200
data	bo3.MatchHistoryResponse	No
data.count	integer	No		20
data.fetched_at	string	No		2026-10-28T10:00:00Z
data.game	string	No		cs2
data.has_more	boolean	No		true
data.limit	integer	No		20
data.matches	array	No
data.matches[].best_of	integer	No		3
data.matches[].end_time	string	No
data.matches[].game	string	No		cs2
data.matches[].id	integer	No		132241
data.matches[].live_coverage	boolean	No		true
data.matches[].maps	array	No			MapRow record, 8 fields: begin_at, loser_score, map, number, status, winner_score, winner_team_id, winner_team_name. Described under BO3.gg match detail API.
data.matches[].prediction	bo3.Prediction	No
data.matches[].prediction.team1_score	integer	No		2
data.matches[].prediction.team2_score	integer	No		1
data.matches[].prediction.winner_team_id	integer	No		654
data.matches[].slug	string	No		spirit-vs-mouz-cs2-27-10-2026
data.matches[].stars	integer	No		4
data.matches[].start_time	string	No		2026-10-27T14:35:00Z
data.matches[].status	string	No	upcoming, current, finished, defwin, canceled, postponed	current
data.matches[].teams	array	No			Team record, 9 fields: country, country_code, id, logo_url, name, rank, score, slug, winner. Described under BO3.gg match detail API.
data.matches[].tier	string	No	s, a, b, c, d	s
data.matches[].tournament	bo3.TournamentRef	No			TournamentRef record, 5 fields: id, name, prize_usd, slug, tier. Described under BO3.gg match detail API.
data.matches[].url	string	No
data.offset	integer	No		0
data.source_url	string	No		https://bo3.gg/matches/current
data.status	string	No		finished,defwin
data.total	integer	No		76604
msg	unknown	No			Msg is the message that describes the result of the request @example "Request successful"

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
404	Not Found	#/definitions/app.Response
429	Too Many Requests	#/definitions/app.Response
503	Service Unavailable	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/bo3/match-history?game=cs2&status=finished&tier=s&sort=newest&limit=10" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

Open in Playground Back to group

BO3.gg esports match history API

Endpoint facts

How this endpoint behaves

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related

BO3.gg esports match history API

Endpoint facts

How this endpoint behaves

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related