Oddin.gg Bragi - Data Feed documentation

Introduction

At Oddin.gg we believe the future belongs to Esports, and we want to help drive that future. Bragi is our data feed: it streams real-time information for every match we distribute. For each match we provide the current live state, score, team and player statistics, and a great deal of supporting information that you can use to power your own products.

1. General information

This chapter explains the core concepts behind the Bragi data feed. If anything below is unclear, please get in touch through your usual Oddin.gg communication channel.

1.1. Concept

The API is built on gRPC and protocol buffers. gRPC is a proven, high-performance framework used at scale by Google, Microsoft and many others. It generates client and server bindings for most popular languages, including Java, C#, Python, Node.js, Go and others. Protocol buffers are used as the message format: they are compact, fast to encode and decode, and well supported across the industry.

• More about gRPC: https://grpc.io
• More about protocol buffers: https://developers.google.com/protocol-buffers

1.2. Environments

Two environments are available. Use the integration environment for all development and testing, and only move to the production environment once your integration is complete and ready for live traffic.

1.3. gRPC schema definition

The full schema is open and published on GitHub:

• Service description: https://github.com/oddin-gg/bragischema
• Protocol buffers schema: https://github.com/oddin-gg/bragischema/tree/main/proto/bragi

You can generate client bindings for your language of choice directly from the .proto files or use one of our pre-generated bindings for Java, Go, or Node.js.

1.4. Authentication

• IP whitelisting: access to the API is allowed only from known IP addresses. Each environment has its own whitelist. Send the IPs (or IP ranges) you want to register, together with the environment name, to your technical integration contact.
• Access token: every call to the data feed must carry a valid access token. You receive a separate token for each environment from our back-office. Tokens are normally valid for one year and are auto-extended.

ℹ️ A maximum of fifty (50) concurrent connections can be made to any of the streams, applied separately to each environment.

1.5. Service definition

The Bragi service exposes both unary calls (single request, single response) and server streams (single request, ongoing stream of responses). The table below summarises every remote procedure call (RPC) defined in the schema.

2. Match timeline

MatchTimeline provides three categories of gRPC endpoints for retrieving real-time and planned match data: Sports, Tournaments and Matches. Each category exposes a unary endpoint for one-off requests and a server-streamed endpoint for continuous updates.

Both count-based endpoints (Sports and Tournaments) use the live_only parameter to choose whether the count should include all matches or only live matches. The Matches endpoints offer the richest filtering, including by URN, sport and team name.

2.1. MatchTimeline sports

Two gRPC endpoints return the list of sports together with a count of current and upcoming matches per sport. The count returned depends on the live_only flag in the request:

• MatchTimelineSports — a one-off (unary) call.
• MatchTimelineSportsFeed — a stream that pushes updates as match counts change.

MatchTimelineSportsRequest / MatchTimelineSportsFeedRequest

MatchTimelineSportsResponse / MatchTimelineSportsFeedResponse

SportMatchCount (nested message)

Example JSON — request and response

// MatchTimelineTournamentsRequest
{
  "live_only": false,
  "sport": "SPORT_CS2"
}

// MatchTimelineTournamentsResponse
{
  "tournaments": [
    {
      "tournament": {
        "urn": "od:tournament:1001",
        "name": "ESL Pro League",
        "is_offline": false,
        "start_date": "2026-03-15T14:00:00Z",
        "organizer_id": 42,
        "organizer_name": "ESL"
      },
      "match_count": 24
    }
  ]
}

2.2. MatchTimeline tournaments

Two gRPC endpoints return the list of tournaments together with a count of current and upcoming matches per tournament. The count returned depends on the live_only flag in the request:

• MatchTimelineTournaments — a one-off (unary) call.
• MatchTimelineTournamentsFeed — a stream that pushes updates as match counts change.

MatchTimelineTournamentsRequest / MatchTimelineTournamentsFeedRequest

MatchTimelineTournamentsResponse / MatchTimelineTournamentsFeedResponse

TournamentMatchCount (nested message)

Example JSON — request and response

// MatchTimelineTournamentsRequest
{
  "live_only": false,
  "sport": "SPORT_CS2"
}

// MatchTimelineTournamentsResponse
{
  "tournaments": [
    {
      "tournament": {
        "urn": "od:tournament:1001",
        "name": "ESL Pro League",
        "is_offline": false,
        "start_date": "2026-03-15T14:00:00Z",
        "organizer_id": 42,
        "organizer_name": "ESL"
      },
      "match_count": 24
    }
  ]
}

2.3. MatchTimeline matches

Two gRPC endpoints return every currently played and planned match:

• MatchTimeline — a oneof (unary) call.
• MatchTimelineFeed — a stream that automatically pushes updates whenever a match status changes.

ℹ️ The MatchTimelineFeed endpoint may include matches that have not yet started. For those matches, you will not have received any update message through the LiveDataFeed yet.

MatchTimelineRequest / MatchTimelineFeedRequest

MatchTimelineResponse

MatchTimelineFeedMessage

Wraps a single frame on the MatchTimelineFeed stream. Exactly one of the oneof fields below is set per message.

Example JSON — MatchTimelineFeedMessage

// Initial timeline frame
{
  "timeline": {
    "matches": [
      {
        "match_urn": "od:match:55501",
        "sport": "SPORT_CS2",
        "home_score": 0,
        "away_score": 0,
        "match_status": "MATCH_STATUS_TYPE_NOT_STARTED",
        "planned_start": "2026-05-27T18:00:00Z",
        "tournament": { "urn": "od:tournament:1001", "name": "ESL Pro League" },
        "teams": [
          { "urn": "od:team:101", "name": "Team Alpha", "is_home": true },
          { "urn": "od:team:202", "name": "Team Bravo", "is_home": false }
        ]
      }
    ]
  }
}

// Subsequent update frame
{
  "match_update": {
    "match_urn": "od:match:55501",
    "sport": "SPORT_CS2",
    "home_score": 1,
    "away_score": 0,
    "match_status": "MATCH_STATUS_TYPE_LIVE"
  }
}

2.4. Common match data structures

The messages below are returned across the MatchTimeline endpoints and are reused throughout the schema. They describe the basic shape of a match, the tournament it belongs to, the teams involved and the players on those teams.

MatchTimeline

Match

Tournament

Team

Player

3. Processing the data feed

3.1. Connection to the data feed

To open the live data stream, the client calls the LiveDataFeed RPC and sends a LiveDataFeedRequest. LiveDataFeedRequest has a single optional timestamp field named after.

When connecting for the first time, leave the after field unset (null). The server then sends the data for every currently played match. If you want to receive matches older than those currently in play, set after to the timestamp of the last update you processed (UNIX milliseconds). The server will then send data for the matches whose latest update was processed at or after that timestamp.

LiveDataFeedRequest

Example JSON — LiveDataFeedRequest

// First-time connection (no "after")
{}

// Reconnect, resuming from the last processed update
{
  "after": "2026-05-27T17:32:11.250Z"
}

3.2. Supported Esports and eSims

Throughout this documentation, the placeholder (Game) is used to refer to any one of the supported Esports or eSims. To use the schema for a specific Esport or eSim, replace (Game) with the relevant prefix (for example, CS2MatchMessage).

3.3. Match state caching

The stream carries information for many matches and several different Esports. Each match is identified by a unique match URN. Your client is expected to process the incoming messages and keep the current state of every active match in its cache.

A match snapshot contains everything the server knows about a match. The client receives one snapshot per match at the start of the stream and keeps it up to date by applying the updates that follow. The details of this update process are described in (Game)MatchSnapshot message below.

3.4. Keepalive

To keep the live feed connection healthy, configure the keepalive settings in your gRPC client. The recommended values are listed below.

ℹ️ Make sure these parameters are set in your gRPC client to keep the live data feed connection stable and responsive.

Sample code (Go)

grpc.WithKeepaliveParams(
  keepalive.ClientParameters{
    Time:                10 * time.Second,
    Timeout:             5  * time.Second,
    PermitWithoutStream: true,
  },
)

3.5. Supported messages

This section describes the protocol buffer messages that flow on the live data feed and how to process them.

3.5.1. LiveDataFeedMessage

LiveDataFeedMessage is the wrapping envelope for every message you receive from the server.

3.5.2. MatchMessage

MatchMessage uses a protocol buffer oneof to carry either an AnnouncementUpdate or a game-specific (Game)MatchMessage. The fields below show the available payload types. Each frame from the server sets exactly one of these fields.

3.5.2.1. AnnouncementUpdate message

An AnnouncementUpdate informs your client about operational events during the life of a match — for example, the match has been postponed, or there will be a server outage. The AnnouncementUpdate wraps an Announcement and adds sequence and timestamp fields. When you receive one, append the Announcement payload to the announcements array on the cached (Game)MatchSnapshot.

AnnouncementUpdate

Announcement

ControlAnnouncement

ControlErrorAnnouncement

Example JSON — AnnouncementUpdate

{
  "match_urn": "od:match:55501",
  "sequence": 432,
  "timestamp": "2026-05-27T17:34:02.110Z",
  "payload": {
    "created_at": "2026-05-27T17:34:02.000Z",
    "payload": {
      "control": {
        "type": "CONTROL_ANNOUNCEMENT_TYPE_UNSPECIFIED",
        "message": "Match postponed by 15 minutes."
      }
    }
  }
}

3.5.2.2. (Game)MatchMessage message

Each sport has its own MatchMessage type — for example, CS2MatchMessage or Dota2MatchMessage. Protocol buffers do not support interfaces or traits, so there is no generic MatchMessage type at the schema level; we use the (Game)MatchMessage label only in this documentation.

Every (Game)MatchMessage has exactly four properties. Three are common to all sports (match_urn, sequence, timestamp); the fourth, payload, is sport-specific (for example, CS2MatchState).

The processing rules are the same across every sport. For brevity, the explanation below uses CS2; the same approach applies to Dota 2, eBasketball and the other games. See Match state processing in section 3.5.2.2.1.1 for more detail.

CS2MatchMessage (representative example of a (Game)MatchMessage)

3.5.2.2.1. (Game)MatchSnapshot message

Each sport has its own snapshot type — for example, CS2MatchSnapshot. Because protocol buffers cannot express a common interface, the schema does not define a generic MatchSnapshot; we use that label only here.

A (Game)MatchSnapshot has exactly five properties. Four are common across all sports (match_urn, sequence, timestamp, announcements); the fifth, match_state, is sport-specific (for example, CS2MatchState).

The snapshot represents the full current state of a match. You receive it exactly once per match, and it is always the first (Game)MatchMessage you see for that match after connecting. Cache the snapshot in memory and apply later update messages (for example, CS2MatchMessage or AnnouncementUpdate) on top of it.

CS2MatchSnapshot (representative example of a (Game)MatchSnapshot)

3.5.2.2.1.1. Match state processing

Match state represents the current state of a match and is cached in the match_state property of the (Game)MatchSnapshot. For simplicity, the rules below are described for CS2 (CS2MatchState), but they apply to every other sport in the same way.

ℹ️ (Game)MatchState is effectively a sub-state of (Game)MatchSnapshot — clients should treat it the same way.

3.5.2.2.2. Updates

Updates are carried inside (Game)MatchMessage messages. The rules below are explained for CS2, but they apply to every other sport in the same way.

Bear in mind that the stream carries messages for many matches at once. We describe the update flow for a single match here, but in practice your client will maintain many match states and their cached snapshots (for example, CS2MatchSnapshot). The rules for applying updates are identical for each.

CS2MatchMessage is the parent of both the initial snapshot and every later update. It carries the sequence and timestamp fields (see (Game)MatchSnapshot for how to apply them to the cached state), a match_urn that identifies the match the update is for, and a oneof payload property with two variants:

3.5.2.2.2.1. (Game)MatchUpdate message

A (Game)MatchUpdate carries content that should be applied to the match_state property of the cached (Game)MatchSnapshot. The update arrives as the payload of a (Game)MatchMessage, which provides the sequence and timestamp fields. Once you have applied the update, replace the cached sequence and timestamp values with the ones from the (Game)MatchMessage.

⚠️ If any update is missing (the sequence number is not exactly one greater than the cached value), the client must recover the whole snapshot by restarting the connection.

A (Game)MatchUpdate contains two fields: payload and events.

ℹ️ For example, when the position of Player 1 changes, the client receives a CS2MatchUpdate with an empty events array and a payload of type CS2MatchStatePartialUpdates containing a single partial update that wraps a CS2PlayerPositionState. When Player 1 kills Player 2, the client receives a CS2MatchUpdate with two CS2Events (a CS2Kill and a CS2Death) and two partial updates that wrap CS2PlayerCurrentRoundStatisticsState, one for each player.

As described above, the payload of a (Game)MatchUpdate is always either a (Game)MatchState or a non-empty array of partial updates. The payload always carries information about a change to the match state. The events field, by contrast, can be empty.

CS2MatchUpdate (representative example)

3.5.2.2.2.1.1. (Game)MatchStatePartialUpdates message

(Game)MatchStatePartialUpdates wraps a non-empty array of idempotent updates to be applied to the match_state property (of type (Game)MatchState) inside (Game)MatchSnapshot. We call each item a partial update (for example, CS2MatchStatePartialUpdate). A partial update is a message containing a sub-state update (which replaces a specific cached sub-state) plus the set of URN properties that locate that sub-state. Note that a partial update can itself wrap another partial update (for example, CS2MatchStatePartialUpdate can wrap CS2CurrentMapStatePartialUpdate).

CS2MatchStatePartialUpdates

3.5.2.2.2.1.2. How to apply partial updates

A partial update is either a oneof protobuf message or a protobuf message with a payload field that is itself a oneof. Each partial update is a wrapper around some sub-state — which replaces a specific cached sub-state — and its URNs. A partial update can wrap another partial update, but the innermost level is always a sub-state.

Partial update message names start with the type they update and end with the suffix PartialUpdate (for example, CS2MatchStatePartialUpdate is applied to the CS2MatchState type). As noted above, a partial update is itself a oneof message, or it contains a nested Payload type that is a oneof. The name of the oneof field matches the name of the property being updated.

Here is a worked example. When the current round's score changes, the client receives a CS2MatchMessage carrying a CS2MatchUpdate with one CS2MatchStatePartialUpdate in the updates array. That partial update is of type CS2MatchScoreState. The fact that the type is CS2MatchScoreState tells you it can only replace CS2MatchScoreState properties, and its score field tells you exactly which property to overwrite.

Example JSON — partial update flow

// CS2MatchMessage carrying a CS2MatchUpdate with one partial update
{
  "match_urn": "od:match:55501",
  "sequence": 1024,
  "timestamp": "2026-05-27T18:14:55.000Z",
  "data_status": "DATA_STATUS_VALID_DATA",
  "payload": {
    "update": {
      "payload": {
        "partial_updates": {
          "updates": [
            {
              "score": {
                "home_score": 9,
                "away_score": 6
              }
            }
          ]
        }
      }
    }
  }
}

3.5.3. MatchSnapshot and MatchState helper wrappers

The schema also defines two helper oneof messages that join all (Game)MatchSnapshot and (Game)MatchState types into a single union. These are convenient when you want a generic container; they are NOT required for maintaining or rebuilding match state, which always uses the game-specific types directly.

MatchSnapshot

MatchState

3.5.4. KeepAlive (deprecated)

KeepAlive was originally a heartbeat message sent periodically from the server. It has been replaced by the built-in gRPC keep-alive (see section 3.4.) and remains in the schema for backwards compatibility.

3.5.5. Common enumerations

The enums below are shared across many of the messages described elsewhere in the schema.

Sport

BestOfType

MatchStatusType

DataStatus

3.6. Player URN format variants

A Player URN is the unique identifier of an individual player (for example, the player_urn property of CS2PlayerMapState) inside the match state. It is central to maintaining a correct match state. The URN is a string made up of three parts separated by colons. The parts and the three URN variants are described below.

1. The first part is always the literal string "od", which is the Oddin.gg system prefix.
2. The second part identifies which variant of the URN you have:

1. The third part is the player-specific identifier, formatted as follows:

Examples of possible player URN variants

4. Match events

In addition to LiveDataFeed, we provide a separate MatchEventsFeed endpoint that streams real-time game events for currently played matches.

4.1. Consuming the feed

To open the match-events stream, the client calls the MatchEventsFeed RPC and sends a MatchEventsFeedRequest.

Once connected, the server begins streaming MatchEventsFeedMessage frames for each active match. The first message for a match is a snapshot of all previous events; later messages each carry a single new event as it happens.

MatchEventsFeedRequest

4.2. MatchEventsFeedMessage

MatchEventsFeedMessage is the wrapping envelope for every match event frame. The payload is a oneof.

4.2.1. CS2MatchEvents

The first frame for a match contains a snapshot of every historical event for that match. Every later frame carries a single new event in real time.

4.2.1.1. CS2Event

A CS2Event records what happened (its event payload), when it happened (its timestamp), and which map it relates to (its map_id).

4.2.1.2. CS2 event types

Only the events listed below are produced for CS2 matches today. The list will grow as we support more event types.

Example JSON — CS2MatchEvents (initial frame, then a real-time update)

// Initial frame: snapshot of historical events
{
  "cs2": {
    "match_urn": "od:match:55501",
    "events": [
      {
        "timestamp": "2026-05-27T18:00:05.000Z",
        "map_id": 1,
        "map_start": { "map_name": "de_mirage" }
      },
      {
        "timestamp": "2026-05-27T18:00:20.000Z",
        "map_id": 1,
        "round_start": {
          "time_remaining": "115s",
          "current_round_number": 1
        }
      }
    ]
  }
}

// Real-time frame: a single new event
{
  "cs2": {
    "match_urn": "od:match:55501",
    "events": [
      {
        "timestamp": "2026-05-27T18:02:42.500Z",
        "map_id": 1,
        "kill": {
          "time_remaining": "67s",
          "current_round_number": 3,
          "killer_position": { "x": 102.3, "y": -45.8, "z": 12.1, "angle": 87.0 },
          "killer_urn": "od:player:7811",
          "killer_team_urn": "od:team:101",
          "victim_urn": "od:player-ext:76561197960287930",
          "victim_team_urn": "od:team:202",
          "weapon": "ak47",
          "headshot": true,
          "penetrated": false,
          "assistants": []
        }
      }
    ]
  }
}

5. Team profile

The TeamProfile RPC returns full, up-to-date information for a team identified by its URN. The response includes team metadata, external identifiers, every player on file for the team, and the players currently set as the map roster. It is a unary (request/response) call.

5.1. TeamProfileRequest

5.2. TeamProfileResponse

5.3.1. TeamProfile

Full profile for a team.

5.3.1.1. PlayerProfile

Profile for an individual player.

5.3.1.1.1. ExternalIdentityList

Wrapper for the list of external identifiers associated with a single provider.

Example JSON — TeamProfileRequest and TeamProfileResponse

// TeamProfileRequest
{
  "team_urn": "od:competitor:12345"
}

// TeamProfileResponse
{
  "team": {
    "urn": "od:competitor:12345",
    "name": "Team Alpha",
    "icon_path": "icons/team_alpha.png",
    "external_identities": {
      "LIQUIPEDIA": { "ids": ["456", "789"] },
      "STEAM":      { "ids": ["76561198000000001"] }
    },
    "players": [
      {
        "urn": "od:player:7811",
        "nickname": "AlphaStar",
        "real_name": "Alex Smith",
        "shortcut": "AST",
        "icon_path": "icons/player_7811.png",
        "age": 22,
        "external_identities": {
          "LIQUIPEDIA": { "ids": ["101"] }
        }
      }
    ],
    "current_map_roster": [
      {
        "urn": "od:player:7811",
        "nickname": "AlphaStar"
      }
    ]
  }
}

6. Game-specific schemas

Every game has its own message and state schema. Each is documented in its own article:

• Oddin.gg Bragi - Game-specific schemas: Counter-Strike 2
• Oddin.gg Bragi - Game-specific schemas: Dota 2
• Oddin.gg Bragi - Game-specific schemas: League of Legends
• Oddin.gg Bragi - Game-specific schemas: Valorant
• Oddin.gg Bragi - Game-specific schemas: eBasketball
• Oddin.gg Bragi - Game-specific schemas: eFootball
• Oddin.gg Bragi - Game-specific schemas: eCricket

7. Content updates

This section lists changes to the documentation and the underlying schema, newest first.

[v0.2.30] - 2026-05-29

• Added SPORT_CS2_DUELS to Sport enum.
• Added extended tables and JSON examples to the documentation.

[v0.2.29] - 2026-05-29

• Added SPORT_RUSH_CRICKET to Sport enum.

[v0.2.28] - 2026-05-20

• Added optional roshan_kills field to Dota 2 team map state.

[v0.2.27] - 2026-05-07

• Reverted the Roshans' logic.

[v0.2.26] - 2026-05-04

• Added organizer info into the Bragi API.

[v0.2.25] - 2026-05-01

• Added active_data_source_type to MatchMessage.

[v0.2.24] - 2026-04-08

• Added Roshans’ logic.

[v0.2.23] - 2026-03-12

• Added multiple external identity sources on the team profile.

[v0.2.22] - 2026-02-27

• Added team profile.

[v0.2.21] - 2026-02-25

• Added player external ID to Live Data Feed.

[v0.2.20] - 2026-02-12

• Added BallPossession field to Rush Basketball map state and partial updates.

[v0.2.19] - 2025-12-09

• Added start_date field to tournaments.

[v0.2.18] - 2025-11-20

• Added Match timeline filtering by team name.

[v0.2.17] - 2025-11-20

• Added Match timeline filtering.

[v0.2.16] - 2025-08-19

• Undeprecated PicksAndBansSelections. The schema now guarantees correct sequencing of picks and bans regardless of connection time and independent of any disruptions in data collection.

[v0.2.15] - 2025-06-05

• Added tournament online/offline flag on LiveDataFeed, MatchTimeline and MatchTimelineFeed.

[v0.2.14] - 2025-05-23

• Live eCricket support.

[v0.2.13] - 2025-04-09

• Added MatchEventsFeed to stream real-time match events. Currently only CS2 is supported.

[v0.2.12] - 2025-04-04

• Added the representation of picks and bans per team.
• Deprecated the previous picks and bans implementation.

[v0.2.11] - 2025-03-27

• Added the parameters timestamp and map_id for CSEvents.
• Added a separate CS2WorldBomb.

[v0.2.10] - 2025-03-06

• Undeprecated CS2 events.
• Added a few attributes.

[v0.2.9] - 2025-01-22

• Added the Roshan position on the minimap.

[v0.2.7] - 2025-01-22

• Added Dota 2 picks and bans ended boolean.

[v0.2.5] - 2024-12-16

• Dota 2 picks and bans were added to Dota2MatchSnapshot and Dota2MatchUpdate, in both the match state and the partial updates, as shown in the protobuf schema.