Filtering and lookups

Every list filter is applied server-side and costs the same single request as an unfiltered call — so filtering is always cheaper than fetching broadly and discarding rows client-side.

Filters combine with AND

curl -H "Authorization: Bearer $ESPORTSODDS_API_KEY" \
  "https://api.esportsodds.gg/v1/cs2/matches?status=completed&date_from=2026-07-01&date_to=2026-07-31&has=rounds"

There is no OR, no negation and no field-expression syntax. Every filter is an exact match on one field, and they narrow together.

What each list accepts

Values are exact and case-sensitive. Two that catch people out:

• region is a full name, not a code: Europe, North America, South America, Asia, CIS, Oceania, Africa. ?region=EU matches nothing.
• role is one of AWP, IGL, Lurker, Rifler, Support — and only about 14% of players have one on file, so the filter excludes every player whose role is simply unknown.

Turning a name into an id

You rarely start with a UUID. Two ways to get one:

Address the resource by slug directly. Teams, players and tournaments accept a slug wherever a path id is expected:

curl -H "Authorization: Bearer $ESPORTSODDS_API_KEY" \
  "https://api.esportsodds.gg/v1/cs2/teams/natus-vincere"

Or filter the list by slug when you want the row in list shape:

curl -H "Authorization: Bearer $ESPORTSODDS_API_KEY" \
  "https://api.esportsodds.gg/v1/cs2/teams?slug=natus-vincere"

?slug= returns the single matching row — or an empty page — in the normal list envelope, and never depends on where the row falls in the paging order. Matches have no slug, so a match id must be a UUID.

See resolving by slug for the pattern in code.

Batch lookups

/players?ids= takes 1–500 comma-separated ids in one request. After reading a match's stat lines you have ten player ids; resolve them all at once rather than ten times:

curl -H "Authorization: Bearer $ESPORTSODDS_API_KEY" \
  "https://api.esportsodds.gg/v1/cs2/players?ids=019f28e1-e6ae-7032-8255-4c7e26548918,019f28e1-e6af-730c-a332-402b928fe87f"

Outside the 1–500 range is a 400.

Dates

date_from and date_to are YYYY-MM-DD, compared against scheduled_at in UTC, and both are inclusive of the whole day — date_to=2026-07-01 includes everything on 1 July. A malformed date is a 400, never a silently ignored filter.