esportsodds.gg

esportsodds

The official Python client for the [esportsodds.gg](https://esportsodds.gg/cs2-api) CS2 data API.

Counter-Strike 2 matches and results, team and player stats, tournaments, rankings and a derived market line, returned as plain Python dicts. Standard library only: there is nothing else to install.

Get CS2 match data and stats without scraping HLTV. This package is a client for a paid API; it is not an official HLTV/Valve API.

Install

pip install esportsodds

Python 3.10 or newer. No dependencies.

Try it first, with no account: set ESPORTSODDS_API_KEY to the public sample key eo_sample_public, which reads a fixed sample of past matches. It is shared by everyone and rate-limited per network address. For evaluation; our Terms apply.

No subscription yet? A free sandbox key reads a fixed sample of past matches, so you can build against real responses first. The quickstart below asks for upcoming matches, which are outside the sample, so with either key start with sandbox_tour.py and a tournament id from the guide. Any request outside the sample raises PermissionDeniedError (sandbox_scope), and its message names the events that work.

Quickstart

from esportsodds import Client

client = Client() # reads ESPORTSODDS_API_KEY from the environment

for match in client.matches.list(status="scheduled", sort="scheduled_at", limit=5).data: print(match["scheduled_at"], match["team_a_name"], "vs", match["team_b_name"])

2026-10-08T14:00:00Z Team A vs Team B

2026-10-08T17:30:00Z Team C vs Team D

Every call returns what the API sent, as ordinary dicts and lists. A list call returns a Page (page.data, page.next_cursor, page.has_more, page.meta); a call for one thing returns a dict.

Matches come newest first unless you say otherwise, which is what you want for results. For scheduled matches that order starts with the fixture furthest away, so the quickstart passes sort="scheduled_at" to get the next ones to be played.

Your API key and the plan

There are two plans, billed monthly or yearly and paid up front: Standard is $99 a month for 50,000 requests and Pro is $299 a month for 150,000 requests. A year costs ten months: $990 a year for Standard and $2,990 a year for Pro, two months free. Requests are counted per account, per calendar month (UTC), across every key the account owns. There is no trial. A free sandbox key reads a fixed sample of past matches, up to 2,000 requests in total, with no card; it is not a plan, and current data needs one. Past your plan's requests, calls get a 429 with the code quota_exceeded until the month resets, and this client raises QuotaExceededError without retrying (retrying cannot help). A spent sandbox key gets sandbox_quota_exceeded, raised the same way (it never resets), and a request outside its sample raises PermissionDeniedError (sandbox_scope, not counted).

The bulk export (matches.bulk() and the walkers built on it) has one more limit. On a Standard account that first subscribed on or after 30 October 2026 you may make up to 250 bulk-export requests a month; past that the API answers 429 with bulk_quota_exceeded, which raises QuotaExceededError without retrying and leaves every other call working. Pro has no bulk limit, and a Standard account that first subscribed before that date has none either.

Create a key in your account after you subscribe, then keep it out of your code:

export ESPORTSODDS_API_KEY="eo_live_..."

• The client sends the key only in the Authorization: Bearer header, never in a URL. It shows only the last four characters in repr() and never puts the key in an error message or a log line.
• It talks HTTPS only. Plain http:// is accepted for localhost and other loopback addresses (127.0.0.1, ::1) alone, and redirects are never followed, so a key cannot be sent to a different host.
• Keep the key on your server. A browser or mobile app should call your backend, not the API.
• You can look at real responses before subscribing on the public demo.

Configuration

A Client is safe to share between threads. Use it as a context manager (with Client() as client:) or call client.close() when you are finished: it closes a custom transport that has a close() method (the default one keeps no connections open, so it has nothing to release).

Methods

Every endpoint is one method. {game} is the client's game, and {id} accepts the UUID or, for teams, players and tournaments, the slug.

Filters are keyword arguments named as in the API reference. A list given for a comma-separated filter (has=["rounds", "depth"], include=["maps", "stats"]) is joined for you; a datetime or