Sister Song

Sister Song Streaming API

Live AI commentary, bets and match data for football, over HTTP, Server-Sent Events and WebSocket.

Always current. Last changed 27 Oct 2026.What's new5 API changes on 27 Oct 2026

Sister Song publishes AI commentary and bets from each strategy (an AI persona), with its live results, and match data: status and scores, events, text commentary, pressure and live odds. Staying up to date explains how we announce changes, and the glossary explains the terms.

How it works

  1. Find a match. GET /fixtures/live lists the matches being streamed. A fixture's id is the match_id you stream.
  2. Open a stream. Over SSE, one HTTP request per match and language. Over a WebSocket, one connection for any number of matches.
  3. Get the replay, then live messages. Every stream starts with a replay of everything already published for the match, then sends each new message as it's published.

Quick start

The examples use FC Barcelona vs Real Madrid (match_id 19732648, 25 October 2026), shortened in places.

  1. Get your token and strategy IDs. Sign in at song.brainanalytics.co. Once Brain Analytics has linked your account to your client, this step shows your token and the IDs of the strategies you can stream. Settings shows the token too. Strategy IDs are short text IDs, such as sister-song-v1.

    Your details

  2. Find a match. Call GET /fixtures/live, or GET /fixtures/upcoming before kick-off. A fixture's id is the match_id you stream.

    curl -H "X-Token: YOUR_TOKEN" https://publisher.prod.song.brainanalytics.co/fixtures/live
    const response = await fetch("https://publisher.prod.song.brainanalytics.co/fixtures/live", {
      headers: { "X-Token": "YOUR_TOKEN" },
    });
    const { fixtures } = await response.json();
    import httpx
    
    response = httpx.get(
        "https://publisher.prod.song.brainanalytics.co/fixtures/live",
        headers={"X-Token": "YOUR_TOKEN"},
    )
    fixtures = response.json()["fixtures"]
  3. Open a stream. SSE is the simplest option: one HTTP request per match.

    curl -N -H "X-Token: YOUR_TOKEN" "https://publisher.prod.song.brainanalytics.co/sse?match_id=19732648&topics=ai-commentary-sister-song-v1,ai-results-sister-song-v1,match_status&language=en"
    const url = new URL("https://publisher.prod.song.brainanalytics.co/sse");
    url.searchParams.set("match_id", "19732648");
    url.searchParams.set("topics", "ai-commentary-sister-song-v1,ai-results-sister-song-v1,match_status");
    url.searchParams.set("language", "en");
    url.searchParams.set("token", "YOUR_TOKEN"); // a browser's EventSource can't send headers
    
    const seen = new Set();
    
    function handle(msg) {
      if (msg.seq) {
        // The end of a replay can repeat the first live messages.
        const key = `${msg.match_id}|${msg.topic}|${msg.language}|${msg.seq}`;
        if (seen.has(key)) return;
        seen.add(key);
      }
      show(msg.publish_type, msg.data);
    }
    
    let delay = 1000;
    
    function connect() {
      const source = new EventSource(url);
      source.onmessage = (event) => {
        delay = 1000;
        const frame = JSON.parse(event.data);
        if (frame.publish_type !== "snapshot") return handle(frame);
        if (frame.chunk === 1) {
          seen.clear();
          clearMatch(); // a new replay is starting
        }
        frame.messages.forEach(handle);
      };
      source.onerror = () => {
        // EventSource reconnects by itself, except after an HTTP error such as a 502 during a deploy.
        if (source.readyState !== EventSource.CLOSED) return;
        setTimeout(connect, delay);
        delay = Math.min(delay * 2, 30000);
      };
    }
    
    connect();
    import json
    
    import httpx
    
    params = {
        "match_id": 19732648,
        "topics": "ai-commentary-sister-song-v1,ai-results-sister-song-v1,match_status",
        "language": "en",
    }
    seen = set()
    
    
    def handle(msg):
        if msg.get("seq"):
            # The end of a replay can repeat the first live messages.
            key = (msg["match_id"], msg["topic"], msg["language"], msg["seq"])
            if key in seen:
                return
            seen.add(key)
        print(msg["publish_type"], msg["data"])
    
    
    # The server sends ": ping" after 15 quiet seconds, so a minute of silence means the connection is gone.
    with httpx.stream(
        "GET",
        "https://publisher.prod.song.brainanalytics.co/sse",
        params=params,
        headers={"X-Token": "YOUR_TOKEN"},
        timeout=httpx.Timeout(10, read=60),
    ) as response:
        response.raise_for_status()
        for line in response.iter_lines():
            if not line.startswith("data: "):
                continue  # ": ok", ": ping" and the blank lines between frames
            frame = json.loads(line[len("data: "):])
            if frame["publish_type"] != "snapshot":
                handle(frame)
                continue
            if frame["chunk"] == 1:
                seen.clear()  # a new replay is starting
            for msg in frame["messages"]:
                handle(msg)

    Tip

    Want to see the stream before writing any code? Try it live replays this match in your browser, with your token.

  4. Read the replay, then live messages. The stream starts with snapshot frames that replay everything already published for the match. After that, you get each new message as it's published. The samples drop the duplicates where the two meet, and start over when a new replay begins (chunk: 1). show and clearMatch stand for your own rendering code.

Before you go live

Check that your client:

  • Drops duplicates on (match_id, topic, language, seq). The end of a replay can repeat the first live messages. See Duplicates and gaps.
  • Starts over on chunk: 1. Every connection, and every WebSocket subscribe, begins with a fresh replay. See Replay frames.
  • Reconnects. Over SSE, reconnect yourself with a backoff after an HTTP error, such as a 502 during a deploy. Over a WebSocket, send {"command": "ping"} at least every 30 seconds. See Reconnecting and Keeping the connection alive.
  • Orders each stream by seq, not by minute. AI minutes hold still through half-time and can step back at full time. See Ordering.
  • Doesn't assume clocks only go up. The period clocks in match_status can jump ahead or back. See Periods.
  • Copes without pressure. Some competitions, currently including the UEFA Champions League, have no pressure messages. See pressure.
  • Keeps what it has shown. We never withdraw a message: a reworded commentary line arrives again, and a disallowed goal is followed by a VAR event. See event.
  • Flips the handicap sign on older bets. Bet slips and tips without handicap_is_line: true carry the opposite sign on handicap markets. See Bet slips.
  • Stores IDs as 64-bit integers. bet_id, wager_selection_id and others already exceed 32 bits.
  • Ignores what it doesn't recognise. We add fields, message types, topics and values without notice. See Staying up to date.

Environments

ProductionStaging
HTTP and SSEhttps://publisher.prod.song.brainanalytics.cohttps://publisher.stage.song.brainanalytics.co
WebSocketwss://publisher.prod.song.brainanalytics.co/wswss://publisher.stage.song.brainanalytics.co/ws

Each environment has its own token. To see the other one, switch environment in the portal: in Settings, or in Your details in the Quick start. Staging runs the same API but covers fewer competitions, so it has fewer matches.

Authentication

Every request except GET /health needs your client token. The Quick start says where to find it. Send it in one of two ways:

  • Header X-Token: YOUR_TOKEN, for server-side clients.
  • Query string ?token=YOUR_TOKEN, for browsers. The browser EventSource and WebSocket APIs can't set headers.

If you send both, the header wins. A missing, unknown or disabled token gets HTTP 403. A WebSocket with a bad token is refused during the handshake, also with 403.

The API accepts cross-origin requests, so browser apps can call it directly.

Topics and languages

A stream is identified by three things: the match (match_id), the topic and the language.

TopicMessage typePer languageContentSent
ai-commentary-{strategy_id}ai_commentaryyesThe strategy's commentary and the bets it placeswhen the strategy acts, every few minutes
ai-results-{strategy_id}ai_resultsnoThe strategy's bets so far and its profit and lossabout once a minute
match_commentarymatch_commentaryyesText commentary from our data provider (not AI)as lines are written
eventeventnoGoals, cards, substitutions, VAR reviews and penaltiesas they happen
match_statusmatch_statusnoMatch state, scores, periods and clockabout once a minute
pressurepressurenoEach team's pressure, minute by minuteevery minute: one message per team
oddsoddsnoAll live odds markets, in IM's formatwhen the odds change

{strategy_id} is the strategy's ID, so the Sister Song strategy's topics are ai-commentary-sister-song-v1 and ai-results-sister-song-v1. A strategy can be limited to certain competitions. Its topics stay empty for matches outside them.

Languages: en (default), zh, vi and th.

  • Per-language topics are published once in each language. English goes out first and the translations usually follow within a few seconds. All copies of an item share the same data.id, so you can use it to match translations.
  • The other topics are published once, with language: "all". They're the same whichever language you choose.

When matches stream: messages start about 15 minutes before kick-off and stop about 30 minutes after full time. You can subscribe earlier. The stream stays empty until the first message.

HTTP endpoints

EndpointResponse
GET /fixtures/live{"fixtures": [LiveFixture]}: matches on the live list. Updated twice a minute.
GET /fixtures/upcoming{"fixtures": [Fixture]}: matches kicking off in the next 3 days, soonest first.
GET /fixtures/im-event-mapping{"mappings": [{"fixture_id": …, "event_id": …}]}: each fixture's IM event_id, for fixtures from yesterday to 14 days ahead.
GET /tips{"tips": [Tip]}: the strategies' bets, written up as tips. See Tips.
GET /health{"status": "ok"}. No token needed.

The live list holds matches in play, plus matches about to kick off (from about 15 minutes before) or just finished. Use state_name to tell them apart.

Both fixture lists show only the matches Sister Song streams. Add ?all=true to also see matches we don't stream.

Fixture, competition, team and event type IDs come from our data provider, Sportmonks. IM's IDs are separate: event_id here, and the IM IDs in odds messages and bet slips. The fixture_id and event_id in the mapping are both integers.

If fixture data is briefly unavailable, the fixture endpoints return 502. Retry after a few seconds.

LiveFixture

idinteger
Fixture ID: use it as match_id
sport_idinteger
Always 1 (football)
league_idinteger
Competition ID
namestring
For example "FC Barcelona vs Real Madrid". It can be "".
state_id, state_nameinteger, string
Match state, for example 22 / "INPLAY_2ND_HALF". See state codes. A state we don't know yet is named "STATE_<id>".
starting_atstring
Kick-off in UTC, for example "2026-10-25T20:00:00"
fixture_whitelistedboolean
true when the match was added on its own rather than through its competition. Every strategy covers such matches. Always false with ?all=true.

Fixture (upcoming)

idinteger
Fixture ID: use it as match_id
sport_idinteger
Always 1 (football)
starting_atstring
Kick-off in UTC
league_id, league_nameinteger, string
Competition
season_id, season_nameinteger, string
Season
stage_id, stage_nameinteger, string
Stage, for example "Regular Season"
round_id, round_nameinteger, string
Round
state_idinteger
Always 1 (not started)
home_team_id, away_team_idinteger
Team IDs
home_team_name, away_team_namestring
Team names
result_infostring
Empty ("") before the match

Missing names are empty strings and missing IDs are 0.

Streaming over SSE

One SSE stream carries one match in one language. Open another stream for another match or language.

HTTP
GET https://publisher.prod.song.brainanalytics.co/sse?match_id=19732648&topics=ai-commentary-sister-song-v1,event,pressure&language=en HTTP/1.1
X-Token: YOUR_TOKEN
match_idintegerRequired
The fixture ID
topicsstringRequired
Comma-separated (topics=a,b) or repeated (topics=a&topics=b)
languagestring
en (default), zh, vi or th. It applies to per-language topics. The other topics always arrive, and with all only they arrive.
tokenstring
Your token, if you can't send the X-Token header

The stream sends, in this order:

  1. : ok (an SSE comment) as soon as you connect.
  2. One or more snapshot frames: the replay (see Replay frames).
  3. Live messages, each on its own data: line.
  4. A : ping comment whenever 15 seconds pass with no messages, to keep the connection open.

Every frame is a default message event, with no event: or id: field. Read publish_type to tell frames apart: it's "snapshot" for replay frames and the message type for everything else.

A live message:

JSON
{
  "timestamp": "2026-10-25T20:26:01.112723",
  "seq": 45,
  "topic": "pressure",
  "match_id": 19732648,
  "language": "all",
  "publish_type": "pressure",
  "data": { "id": 7308289375, "minute": 23, "pressure": 45.3, "participant_id": 83, "side": "home" },
  "id": null
}
timestampstring
When the message was published, in UTC (see Times)
seqinteger or null
The message's position in its stream (see Duplicates and gaps)
topicstring
The topic
match_idinteger
The fixture ID
languagestring
en, zh, vi or th, or all on the topics that aren't per language
publish_typestring
The message type, such as pressure (see Message reference)
dataobject
The message
idnull
Always null on live messages. Messages inside a replay carry their stored id and created_at.

Errors. 400 if topics is missing, 422 if match_id is missing or a parameter is invalid, and 403 for a bad token.

Reconnecting

  • The server ends your stream if you fall more than 256 messages behind. Streams also end when the service restarts, for example during a deploy.
  • A browser's EventSource reconnects by itself after a dropped connection. After an HTTP error response, such as 502 during a deploy, it stops for good, so reconnect yourself with a backoff, as the Quick start sample does.
  • Every new connection starts with a fresh replay.

Streaming over WebSocket

One WebSocket can hold many subscriptions: several matches, topics and languages. All messages are JSON text, in both directions.

Connect to wss://publisher.prod.song.brainanalytics.co/ws?token=YOUR_TOKEN, or send the X-Token header instead if your WebSocket library can.

Commands

CommandFieldsReply
subscribetopic, match_id, language (default en)One ack per topic with status: "subscribed", then the replay frames
unsubscribetopic, match_id, language (default en)One ack per topic with status: "unsubscribed"
unsubscribe_all_by_match_idmatch_idOne ack with status: "unsubscribed_all_by_match_id"
unsubscribe_allnoneOne ack with status: "unsubscribed_all"
pingnone{"type": "pong"}
commandstring
One of the commands above. Others get no reply.
topicstring or array of string
One topic, a comma-separated string or a JSON array. Needed by subscribe and unsubscribe.
match_idinteger
The fixture ID. Needed by every command except unsubscribe_all and ping.
languagestring
en (default), zh, vi or th, as on SSE. all subscribes to the topics that aren't per language only.

The replay after a subscribe covers all the topics in that command. language works as it does on SSE. It sets the language of the per-language topics, and the other topics arrive whatever language you send. So one command covers a whole match:

JSON
{ "command": "subscribe", "topic": "ai-commentary-sister-song-v1,ai-results-sister-song-v1,match_commentary,event,match_status,pressure,odds", "match_id": 19732648, "language": "en" }

To unsubscribe, send the same topics and language.

An ack:

JSON
{
  "type": "ack",
  "timestamp": "2026-10-25T21:40:00.123456",
  "match_id": 19732648,
  "language": "en",
  "topic": "ai-commentary-sister-song-v1",
  "status": "subscribed",
  "error": null
}
typestring
Always "ack"
timestampstring
When it was sent, in UTC
match_idinteger or null
The command's fixture ID
languagestring or null
The command's language
topicstring or null
One topic from the command
statusstring
subscribed, unsubscribed, unsubscribed_all_by_match_id, unsubscribed_all or error
errorstring or null
What was wrong with the command, when status is error

Subscribing again to something you already hold is harmless. You get a new ack and a fresh replay.

Live messages

JSON
{
  "type": "pressure",
  "timestamp": "2026-10-25T20:26:01.112723",
  "match_id": 19732648,
  "language": "all",
  "topic": "pressure",
  "seq": 45,
  "data": { "id": 7308289375, "minute": 23, "pressure": 45.3, "participant_id": 83, "side": "home" }
}

Live WebSocket messages have the same fields as live SSE messages, except that they give their type in type and have no id. Messages inside replay frames use publish_type, as on SSE.

Keeping the connection alive

If the server receives nothing from you for 60 seconds, it drops every subscription on that connection and sends:

JSON
{ "type": "unsubscribed", "reason": "timeout" }

The socket stays open, but you have to subscribe again.

Important

Send {"command": "ping"} every 30 seconds. WebSocket ping frames, which many libraries send by themselves, don't count: only a message from you resets the timer.

Errors

A command with no topic or match_id, or with an unknown language, gets an error ack:

JSON
{ "type": "ack", "timestamp": "2026-10-25T21:40:00.123456", "match_id": 19732648, "language": null, "topic": null, "status": "error", "error": "Missing topic or match_id" }

Unknown commands get no reply. A frame that isn't a JSON object closes the connection.

Example client

const socket = new WebSocket("wss://publisher.prod.song.brainanalytics.co/ws?token=YOUR_TOKEN");
const subscribe = {
  command: "subscribe",
  topic: "ai-commentary-sister-song-v1,ai-results-sister-song-v1,match_status",
  match_id: 19732648,
  language: "en",
};
const seen = new Set();
let pinger;

function handle(msg, type) {
  if (msg.seq) {
    const key = `${msg.match_id}|${msg.topic}|${msg.language}|${msg.seq}`;
    if (seen.has(key)) return;
    seen.add(key);
  }
  show(type, msg.data);
}

socket.onopen = () => {
  socket.send(JSON.stringify(subscribe));
  pinger = setInterval(() => socket.send(JSON.stringify({ command: "ping" })), 30000);
};

socket.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  switch (msg.type) {
    case "ack":
    case "pong":
      return;
    case "unsubscribed": // nothing heard from us for 60 seconds
      return socket.send(JSON.stringify(subscribe));
    case "snapshot":
      if (msg.chunk === 1) {
        seen.clear();
        clearMatch(); // a new replay is starting
      }
      return msg.messages.forEach((item) => handle(item, item.publish_type));
    default:
      return handle(msg, msg.type);
  }
};

socket.onclose = () => clearInterval(pinger); // then reconnect, with a backoff
import asyncio
import json

import websockets

URL = "wss://publisher.prod.song.brainanalytics.co/ws?token=YOUR_TOKEN"
SUBSCRIBE = {
    "command": "subscribe",
    "topic": "ai-commentary-sister-song-v1,ai-results-sister-song-v1,match_status",
    "match_id": 19732648,
    "language": "en",
}
seen = set()


def handle(msg, kind):
    if msg.get("seq"):
        key = (msg["match_id"], msg["topic"], msg["language"], msg["seq"])
        if key in seen:
            return
        seen.add(key)
    print(kind, msg["data"])


async def keep_alive(socket):
    # The library's own WebSocket pings don't reset the server's 60-second timer. This does.
    while True:
        await asyncio.sleep(30)
        await socket.send(json.dumps({"command": "ping"}))


async def main():
    # Replay frames of odds can pass the library's default 1 MB message limit.
    async with websockets.connect(URL, max_size=None) as socket:
        await socket.send(json.dumps(SUBSCRIBE))
        pinger = asyncio.create_task(keep_alive(socket))
        try:
            async for raw in socket:
                msg = json.loads(raw)
                if msg["type"] in ("ack", "pong"):
                    continue
                if msg["type"] == "unsubscribed":  # nothing heard from us for 60 seconds
                    await socket.send(json.dumps(SUBSCRIBE))
                elif msg["type"] == "snapshot":
                    if msg["chunk"] == 1:
                        seen.clear()  # a new replay is starting
                    for item in msg["messages"]:
                        handle(item, item["publish_type"])
                else:
                    handle(msg, msg["type"])
        finally:
            pinger.cancel()


asyncio.run(main())

Session overview

sequenceDiagram
  accTitle: A WebSocket session
  autonumber
  participant C as Your app
  participant P as Publisher

  C->>P: GET /fixtures/live (X-Token)
  P-->>C: 200 {fixtures: [...]}

  C->>P: WebSocket /ws?token=...
  P-->>C: connection accepted

  C->>P: subscribe ai-commentary-sister-song-v1,ai-results-sister-song-v1,event,... (language "en")
  P-->>C: one ack per topic, then snapshot frames 1..n

  loop every 30 s
    C->>P: {command: "ping"}
    P-->>C: {type: "pong"}
  end

  P-->>C: live messages: ai_commentary, ai_results, match_commentary, event, match_status, pressure, odds

Replays, ordering and duplicates

Replay frames

When you connect over SSE, or subscribe over a WebSocket, you first get a replay. It holds every message already published for that match and those topics, oldest first, split into frames of up to 30 messages. You always get at least one frame. If nothing has been published yet, its messages list is empty.

JSON
{
  "type": "snapshot",
  "publish_type": "snapshot",
  "timestamp": "2026-10-25T21:40:00.512345",
  "match_id": 19732648,
  "language": "en",
  "topics": ["ai-commentary-sister-song-v1", "pressure"],
  "chunk": 1,
  "total_chunks": 8,
  "messages": [
    {
      "id": 1940582,
      "created_at": "2026-10-25T19:46:11.147292Z",
      "timestamp": "2026-10-25T19:46:11.127134Z",
      "seq": 1,
      "topic": "ai-commentary-sister-song-v1",
      "match_id": 19732648,
      "language": "en",
      "publish_type": "ai_commentary",
      "data": {
        "id": "5792b134-ee1d-456d-89ec-271db69a88bd",
        "minute": 0,
        "period_id": 0,
        "period_name": "Not Started",
        "commentary": "Welcome everyone to our stream, let's analyze this massive El Clásico together and find some smart investments!",
        "action_type": "welcome",
        "bet_slips": []
      }
    }
  ]
}
type, publish_typestring
Both "snapshot"
timestampstring
When the frame was built, in UTC
match_idinteger
The fixture ID
languagestring
The language you asked for
topicsarray of string
The topics replayed, in any order
chunk, total_chunksinteger
This frame's number, from 1, and how many frames the replay has
messagesarray of object
Up to 30 messages, oldest first. They have the fields of live SSE messages, plus their stored id (an integer) and created_at.
  • chunk: 1 always starts a new replay. Drop what you hold for those topics, then apply the frames in order. You're up to date when chunk equals total_chunks.
  • Replays of older matches can lack fields added since. Treat a missing field like null.

Note

odds and match_status replay every message sent so far, though only the latest one is current. Late in a match, an odds replay can be several megabytes, and a single frame can pass 1 MB.

Duplicates and gaps

  • seq starts at 1 and goes up by 1 within each stream (match, topic and language).
  • The end of a replay can overlap the first live messages. Drop duplicates on (match_id, topic, language, seq).
  • Rarely, a live message has seq: null, or 0 on its translations: we couldn't store it, so it won't appear in any replay. Show it without deduplicating it.
  • A replay can be up to 5 seconds old. So a message published just before you connected can be missing from both the replay and the live stream. If a stream's seq skips a number, resubscribe or reconnect a few seconds later to fill the gap.

Ordering

  • Within one stream, order messages by seq.
  • seq is counted separately for each stream, so it can't order messages across topics. Across topics, use timestamp (when the message was published) or the match minute in data.

Times

All times are UTC. Live messages, acks and replay frames have no zone suffix (2026-10-25T20:26:01.112723). Messages inside a replay, and tips' created_at, end in Z. Treat both as UTC. The fractional seconds are left out when they're zero.

Message reference

Each section shows the data of one message type.

Note

Store IDs as 64-bit integers. bet_id, wager_selection_id (wsid in odds), market_line_id (mlid) and pressure id already exceed 32 bits. They're all well within the range JavaScript numbers hold exactly.

ai_commentary

The strategy's commentary, and any bets it places.

JSON
{
  "id": "8f4cf6e8-5cf4-4c36-88e9-b58c974e9d78",
  "minute": 75,
  "period_id": 2,
  "period_name": "2nd-half",
  "commentary": "Barcelona are dominating the possession charts and forcing errors. Let us grab the 1X2 market for a home win at 2.6 while the price is high.",
  "action_type": "snipe_live_bet",
  "bet_slips": [
    {
      "bet_id": 1792964349638601,
      "market_line_id": 2552318214,
      "market_name": "1X2",
      "bet_type_id": 3,
      "period_id": 1,
      "selection_id": 5,
      "selection_name": "Home",
      "wager_selection_id": 33142892065,
      "odds": 2.6,
      "handicap": null,
      "handicap_is_line": true,
      "specifiers": "",
      "odds_type": null,
      "stake": 25.0,
      "bet_placed_home_score": 1,
      "bet_placed_away_score": 1,
      "bet_placed_home_corners": 4,
      "bet_placed_away_corners": 6,
      "im_home_team_id": 80987,
      "im_away_team_id": 870,
      "confidence": 0.45,
      "implied_probability": 0.38,
      "confidence_source": "model"
    }
  ]
}
idstring or null
The item's UUID. It's the same in every language. It can be null on old messages.
minuteinteger
Match minute when the strategy acted
period_id, period_nameinteger, string
0 "Not Started", 1 "1st-half", 2 "2nd-half", 3 "extra-time" or 5 "penalties"
commentarystring
The text, in the stream's language
action_typestring
What the strategy is doing (see Action types)
bet_slipsarray of bet slips
The bets placed by this action. Empty when there are none.

Note

AI minutes don't always go up. The minute on ai_commentary and ai_results holds still through half-time and can step back at full time. Order a strategy's messages by seq.

Action types

Use them to drive your UI, for example icons or colours.

Groupaction_typeThe strategy…
Bettingsnipe_live_betbets on a value opportunity
double_downadds another bet on an outcome it already backs
hedge_betbets against one of its bets to lock in a result
cash_out_decisiontakes a profit or cuts a loss
cash_out_temptationdebates whether to cash out
tilt_betbets aggressively after a loss
Advicehighlight_valuepoints out value without betting
warn_trapwarns against a bet
suggest_fun_betsuggests a long shot for fun
Reactionsreact_goal_favoredcelebrates a goal that helps its bets
react_goal_opposedreacts to a goal that hurts its bets
react_goal_neutralappreciates a goal it has no stake in
react_var_checkwaits on a VAR decision
react_near_missreacts to a shot off the post or a big save
analyze_momentumcomments on the flow of the game
critique_playerblames a player
Moodsweatingfeels the tension late in a close bet
bragginggloats after a win
copingexplains away a loss
rally_cryurges a result ("One more corner!")
Audienceask_chat_opinionasks viewers what they think
shoutout_winnerscelebrates with viewers who won
Sessionwelcomeopens the stream, before or at kick-off
goodbyesigns off after the match

Bet slips

ai_results and tips reuse the same fields.

bet_idinteger
Unique bet ID. It also appears in ai_results and tips.
market_line_idinteger
IM market line ID (mlid in odds)
market_namestring
For example "Handicap", "Over/Under", "1X2", "1H Over/Under" or "Corner Handicap"
bet_type_idinteger or null
IM bet type ID (btid in odds)
period_idinteger or null
IM game period: 1 full match, 2 first half, 3 second half
selection_id, selection_nameinteger, string
The selection, for example 5 "Home" on 1X2, or 3 "Over"
wager_selection_idinteger or null
IM wager selection ID (wsid in odds)
oddsnumber
Decimal odds when the bet was placed
handicapnumber or null
The line bet on this selection, for example -0.5 for Home −0.5, or the total on over/under markets. null on markets without one.
handicap_is_lineboolean
true on current slips. Older slips don't have it: see the warning below.
specifiers, odds_typestring or null, integer or null
IM details. Usually "" and null.
stakenumber
Stake, in notional units. PnL uses the same units.
bet_placed_home_score, bet_placed_away_scoreinteger
Score when the bet was placed
bet_placed_home_corners, bet_placed_away_cornersinteger or null
Corners when the bet was placed. null on old bets.
im_home_team_id, im_away_team_idinteger or null
IM team IDs
confidencenumber or null
The strategy's estimate of the chance the bet wins, from 0 to 1. Show it as a percentage.
implied_probabilitynumber or null
1 / odds when the bet was placed, from 0 to 1
confidence_sourcestring or null
"model" when confidence is the strategy's own estimate. "market" when it gave none, so confidence equals implied_probability.

The three confidence fields are rounded to 2 decimal places. They're all null on old bets, and when the odds were 1 or lower.

Warning

Older bets have the opposite handicap sign. Current bet slips and tips have handicap_is_line: true. Older ones don't have it, or have false, and on handicap markets (where market_name or market_type contains "Handicap") their handicap is the negative of the line bet. For example, "selection_name": "Away", "handicap": -0.25 without the marker was a bet on Away +0.25, so flip the sign when you display it. Over/under lines and the odds topic were always correct.

ai_results

The strategy's results for the match, about once a minute. Each message gives the full picture so far, not a change.

JSON
{
  "settled_pnl": 15.25,
  "unsettled_pnl": 0.0,
  "minute": 76,
  "bets": [
    {
      "bet_slip": { "bet_id": 1792959428604594, "market_name": "1H Over/Under", "selection_name": "Over", "odds": 1.84, "handicap": 1.25, "stake": 25.0 },
      "state": "half_lost",
      "live_state": "half_lost",
      "settled": true,
      "pnl": -12.5
    },
    {
      "bet_slip": { "bet_id": 1792964349638601, "market_name": "1X2", "selection_name": "Home", "odds": 2.6, "handicap": null, "stake": 25.0 },
      "state": "pending",
      "live_state": "lost",
      "settled": false,
      "pnl": 0.0
    }
  ]
}

The bet_slip objects are shortened here. Real ones have every bet slip field.

settled_pnlnumber
Profit or loss from settled bets. This is the strategy's PnL.
unsettled_pnlnumber
Always 0: a bet adds to PnL only once it settles
minuteinteger
Match minute
betsarray of object
Every bet the strategy has placed in this match

Each entry in bets:

bet_slipobject
The bet, as in ai_commentary
statestring
pending, won, lost, half_won, half_lost or push
live_statestring
What the bet would settle as if the match ended now (same values). It equals state once the bet settles. Some old messages don't have it.
settledboolean
true once the result is final
pnlnumber
Profit or loss on this bet. 0 until it settles.

match_commentary

Text commentary from our data provider. It's translated into each language.

JSON
{
  "id": 11580888,
  "minute": 41,
  "extra_minute": null,
  "comment": "Goal! Real Madrid lead 1-0 against Barcelona as Kylian Mbappé scores with a right-footed shot from the center of the box into the bottom left corner.",
  "is_goal": true,
  "is_important": true
}
idinteger
Line ID. It's the same in every language.
minute, extra_minuteinteger, integer or null
Match minute, and minutes into stoppage time: 90 and 8 mean 90+8'. extra_minute is null outside stoppage time.
commentstring
The text, in the stream's language
is_goalboolean
true on goal lines
is_importantboolean
true on key moments

minute is always set. A line without its own minute gets the minute of the line before it, or 0 if there's none.

Note

Messages are never withdrawn. If our data provider rewords a commentary line, you get both versions.

event

Structured match events.

JSON
{
  "id": 158411184,
  "type_id": 14,
  "type_name": "Goal",
  "minute": 61,
  "extra_minute": null,
  "period_id": 7194994,
  "side": "home",
  "participant_id": 83,
  "player_id": 160258,
  "player_name": "Raphinha",
  "related_player_id": 37288001,
  "related_player_name": "Pedri",
  "result": "1-1",
  "info": "Right foot shot",
  "addition": "2nd Goal",
  "sort_order": 2,
  "rescinded": null,
  "coach_id": null,
  "on_bench": false,
  "injured": null
}
idinteger
Event ID
type_id, type_nameinteger, string
Event type (see Event types)
minute, extra_minuteinteger, integer or null
Match minute and minutes into stoppage time. For penalty shootout kicks, minute is the kick number.
period_idinteger or null
ID of the period it happened in. It matches periods[].id in match_status.
sidestring
"home" or "away". Events without a team are reported as "home".
participant_idinteger or null
Team ID
player_id, player_nameinteger or null, string or null
The main player: the scorer, the booked player or the player coming on
related_player_id, related_player_nameinteger or null, string or null
The other player: the assist, or the player going off
resultstring or null
Score after a goal, for example "1-1"
infostring or null
Detail, for example "Right foot shot" or "Unsportsmanlike conduct"
additionstring or null
Label, for example "2nd Goal", "6th Yellowcard" or "Goal disallowed"
sort_orderinteger or null
How many events of this type there have been so far (the 2 in "2nd Goal"). It doesn't order events within a minute.
rescinded, on_benchboolean or null
Other details, often null
coach_idinteger or null
Other details, often null
injuredboolean, string or null
Other details, often null

Only id, type_id, type_name, minute and side are always set.

Note

Events are sent once and never updated. A goal later disallowed stays in the feed, followed by a VAR event with addition: "Goal disallowed".

Event types

type_idtype_name
14Goal
15Own Goal
16Penalty (scored)
17Missed Penalty
18Substitution
19Yellowcard
20Redcard
21Yellow/Red card
10VAR
1697VAR_CARD
22Penalty Shootout Miss
23Penalty Shootout Goal

Other Sportmonks event types may appear. Corners aren't sent as events. VAR events say what happened in addition, for example "Pending VAR", "Goal disallowed" or "Penalty awarded".

pressure

How much pressure each team is putting on, minute by minute. Each minute has two messages, one per team.

JSON
{ "id": 7308289375, "minute": 23, "pressure": 45.3, "participant_id": 83, "side": "home" }
idinteger
Reading ID
minuteinteger
Match minute
pressurenumber
That team's pressure in that minute, from 0 to 100
sidestring or null
"home" or "away". It can be null if the team isn't recognised.
participant_idinteger or null
Team ID

To show momentum, compare the two teams' values for each minute.

Note

Not every competition has pressure. Some, currently including the UEFA Champions League, send no pressure data, so their matches have no pressure messages.

match_status

The full current state of the match. It's sent about once a minute, and only once during half-time.

JSON
{
  "id": 19732648,
  "name": "FC Barcelona vs Real Madrid",
  "state": { "name": "2nd Half", "short_name": "2nd" },
  "result_info": null,
  "starting_at": "2026-10-25 20:00:00",
  "scores": [
    { "score": { "goals": 0, "participant": "home" }, "description": "CURRENT", "participant_id": 83 },
    { "score": { "goals": 1, "participant": "away" }, "description": "CURRENT", "participant_id": 3468 },
    { "score": { "goals": 0, "participant": "home" }, "description": "1ST_HALF", "participant_id": 83 },
    { "score": { "goals": 1, "participant": "away" }, "description": "1ST_HALF", "participant_id": 3468 }
  ],
  "periods": [
    { "id": 7194899, "fixture_id": 19732648, "type_id": 1, "description": "1st-half", "sort_order": 1, "started": 1792958554, "ended": 1792961389, "ticking": false, "minutes": 47, "seconds": 15, "time_added": 2, "has_timer": false },
    { "id": 7194994, "fixture_id": 19732648, "type_id": 2, "description": "2nd-half", "sort_order": 2, "started": 1792962497, "ended": null, "ticking": true, "minutes": 53, "seconds": 43, "time_added": null, "has_timer": true }
  ]
}
id, nameinteger, string
Fixture ID and name
stateobject or null
Match state: name and short_name, both strings (see Match states)
result_infostring or null
Result text after the match, for example "Real Madrid won after full-time.". null before.
starting_atstring
Kick-off in UTC, written "2026-10-25 20:00:00" (with a space, not T)
scoresarray of object or null
Scores, one entry per team for each description (see Scores)
periodsarray of object or null
The periods played so far (see Periods)

Scores

score.goalsinteger
Goals
score.participantstring
"home" or "away"
descriptionstring
Which score this is (see below)
participant_idinteger
Team ID

CURRENT is the live score. 1ST_HALF is the half-time score, 2ND_HALF the score after the second half (so far), and 2ND_HALF_ONLY the goals scored in the second half alone. ET, ET_1ST_HALF, ET_2ND_HALF and PENALTY_SHOOTOUT appear when extra time or a shootout is played.

Periods

idinteger
Period ID. Events' period_id points here.
type_id, descriptioninteger, string
1 "1st-half", 2 "2nd-half", 3 "extra-time" or 5 "penalties"
sort_orderinteger
Order of the period
started, endedinteger or null
Unix time in seconds. ended is null while the period runs.
tickingboolean
true while the clock runs
minutes, secondsinteger or null
The match clock, for example 53:43. The second half carries on from 45. minutes is null if the provider sends an implausible value.
time_addedinteger or null
Stoppage time announced, in minutes
has_timerboolean
true while the provider times the period. It's false once the period ends, and for penalties.
fixture_idinteger
Fixture ID

Note

Period clocks can jump. They come from our data provider, and now and then they jump ahead or back, for example at second-half kick-off. Don't assume they only increase.

Match states

state.name / state.short_name: Not Started / NS, 1st Half / 1st, Half Time / HT, 2nd Half / 2nd, Extra Time / et, Extra Time - Break / ETB, Penalties / PEN, Break / BRK, Full Time / FT, After Extra Time / AET, After Penalties / FTP, Postponed / POST, Delayed / DELA, Suspended / SUSP, Interrupted / INT, Abandoned / ABAN, Awaiting Updates / AU.

State codes

state_id and state_name in fixtures, and match_state in tips, use these codes:

  • Not started: 1 NS
  • In play: 2 INPLAY_1ST_HALF, 3 HT, 4 BREAK, 22 INPLAY_2ND_HALF, 6 INPLAY_ET, 21 EXTRA_TIME_BREAK, 23 INPLAY_ET_2ND_HALF, 25 PEN_BREAK, 9 INPLAY_PENALTIES
  • Finished: 5 FT, 7 AET, 8 FT_PEN
  • Other: 10 POSTPONED, 11 SUSPENDED, 12 CANCELLED, 13 TBA, 14 WO, 15 ABANDONED, 16 DELAYED, 17 AWARDED, 18 INTERRUPTED, 19 AWAITING_UPDATES, 20 DELETED, 26 PENDING

odds

Every live market for the match, in IM's compact format. Each message holds the full list, so replace what you have.

JSON
{
  "ht": "Barcelona",
  "at": "Real Madrid",
  "htid": 80987,
  "atid": 870,
  "hs": 0,
  "as": 1,
  "rbt": "2H 53:53",
  "mls": [
    {
      "btn": "Handicap",
      "btid": 1,
      "mlid": 2552318204,
      "gp": 1,
      "mll": 1,
      "isl": false,
      "pen": null,
      "peid": null,
      "wss": [
        { "sen": "Home", "seid": 1, "wsid": 33142524486, "h": 0.5, "dih": "-0.5", "o": 0.86, "ol": [{ "ot": 3, "ov": { "A": "1.86" } }], "sp": "" },
        { "sen": "Away", "seid": 2, "wsid": 33142524487, "h": 0.5, "dih": "+0.5", "o": -0.94, "ol": [{ "ot": 3, "ov": { "A": "2.06" } }], "sp": "" }
      ]
    }
  ]
}

Top level

ht, atstring
Home and away team names, as IM names them
htid, atidinteger or null
IM team IDs
hs, asinteger or null
Current score, according to IM
rbtstring or null
IM's match clock, for example "2H 53:53"
mlsarray of object
Market lines

Market lines (mls)

btnstring
Market name, for example "Handicap", "1H Over/Under" or "Corner Handicap"
btidinteger
IM bet type ID (bet_type_id on bet slips)
mlidinteger
Market line ID (market_line_id on bet slips)
gpinteger or null
Game period: 1 full match, 2 first half, 3 second half
mllinteger
Line level: 1 is the main line, and 2 and above are alternative lines
islboolean
true when the market is locked and can't be bet on
wssarray of object
Selections
pen, peidstring or null, integer or null
Old period fields, usually null

Selections (wss)

senstring or null
Selection name, for example "Home", "Over", "Draw" or "1-2"
seidinteger or null
Selection ID (selection_id on bet slips)
wsidinteger or null
Wager selection ID (wager_selection_id on bet slips)
olarray of object
The decimal price, as a string: [{"ot": 3, "ov": {"A": "1.86"}}]. Use this for prices. It can be empty.
onumber or null
IM's raw price. Its format depends on the market, so use ol instead.
hnumber or null
The line. On handicap markets, both selections carry the same number: the handicap Home gives. h: 0.5 means Home −0.5 and Away +0.5. On over/under markets, it's the total.
dihstring or null
The line as IM displays it for this selection, for example "-0.5" or "+0.5/1" (a quarter line, split across two lines)
spstring or null
Specifiers, usually ""

Warning

Read prices from ol, not o. IM's raw price in o is in Malay format on handicap and over/under markets and decimal on the others, so the same number means different odds.

Tips

GET /tips returns the strategies' bets as tips: the bet, a short written reason, and whether you can still follow it.

languagestring
en (default), zh, vi or th. all returns 400.
strategy_idstring
Only tips from this strategy
match_idinteger
Only tips for this match
live_onlyboolean
true (default): only tips you can still follow now. false: the newest tips whatever their status, each with its current status.

You get up to 200 tips, newest first. Each bet becomes one tip per language.

A tip is live (is_live: true) when all of these are true:

  • the match is in play
  • the tip is less than 30 minutes old
  • the bet hasn't settled, and the strategy hasn't cashed it out or hedged it
  • the score hasn't changed since the bet was placed
  • the same selection and line are still on offer, unlocked, at odds of at least minimum_odds
JSON
{
  "bet_id": 1792964349638601,
  "match_id": 19732648,
  "strategy_id": "sister-song-v1",
  "language": "en",
  "market_type": "1X2",
  "selection": "Home",
  "handicap": null,
  "handicap_is_line": true,
  "odds": 2.6,
  "odds_type": "decimal",
  "minimum_odds": 2.6,
  "current_odds": 2.62,
  "probability": 0.45,
  "implied_probability": 0.38,
  "estimated_odds": 2.2222,
  "expected_value": 0.17,
  "bet_type_id": 3,
  "selection_id": 5,
  "period_id": 1,
  "market_line_id": 2552318214,
  "im_competition_id": 130,
  "home_team_id": 83,
  "away_team_id": 3468,
  "home_team_name": "FC Barcelona",
  "away_team_name": "Real Madrid",
  "placed_minute": 75,
  "placed_home_score": 1,
  "placed_away_score": 1,
  "tips_summary": "FC Barcelona are dominating possession and applying sustained attacking pressure as the match enters the final stages.",
  "tips_reasoning": "- FC Barcelona hold 60 percent of the ball possession and lead the total shots count 14 to 8.\n- The hosts have generated 44 dangerous attacks compared to Real Madrid's 23.\n- Barcelona lead the shots inside the box with 9 attempts against Real Madrid's 4.",
  "created_at": "2026-10-25T21:39:10.767092Z",
  "is_live": true,
  "bet_state": "pending",
  "settled": false,
  "current_home_score": 1,
  "current_away_score": 1,
  "current_minute": 76,
  "match_state": "INPLAY_2ND_HALF"
}
bet_id, match_idinteger
Which bet and match
strategy_id, languagestring
Which strategy, and the tip's language
market_type, selectionstring
Market and selection, as on the bet slip
handicapnumber or null
The line, as on the bet slip
handicap_is_lineboolean
true on current tips. On older ones, flip the sign: see Bet slips.
oddsnumber
Odds when the bet was placed
odds_typestring
Always "decimal"
minimum_oddsnumber
The lowest odds at which the tip is still worth taking. Currently the same as odds.
current_oddsnumber or null
Latest decimal odds for the same selection and line. null if it's no longer on offer.
probabilitynumber or null
The strategy's estimate of the chance the bet wins, from 0 to 1. null if it gave none.
implied_probabilitynumber or null
1 / odds when the bet was placed
estimated_oddsnumber or null
1 / probability
expected_valuenumber or null
probability × odds − 1: 0.17 means +17%
bet_type_id, period_idinteger or null
IM IDs, as on the bet slip
selection_id, market_line_idinteger
IM IDs, as on the bet slip
im_competition_idinteger or null
IM competition ID
home_team_id, away_team_idinteger
Team IDs
home_team_name, away_team_namestring
Team names, in the tip's language
placed_minute, placed_home_score, placed_away_scoreinteger
Minute and score when the bet was placed
tips_summarystring
One line on why
tips_reasoningstring
Up to 3 bullet points, as markdown lines starting with -
created_atstring
When the tip was made, in UTC
is_liveboolean
Whether you can still follow the tip (see above)
bet_statestring or null
The bet's state (pending, won, …). null when unknown.
settledboolean
Whether the result is final. false when unknown.
current_home_score, current_away_score, current_minuteinteger or null
The match now. null when unknown.
match_statestring or null
A state code name, or "unknown". null when unknown.

Staying up to date

This guide always describes the current production API, at song.brainanalytics.co/docs.

  • Changelog. Every change is listed, newest first, at song.brainanalytics.co/docs/changelog. To hear about changes as they happen, subscribe to its feed, https://song.brainanalytics.co/docs/changelog.xml, in a feed reader or in Slack with /feed subscribe https://song.brainanalytics.co/docs/changelog.xml.
  • Additions come without notice. We add fields, message types, topics and values (such as new action_type values) as we go. Ignore anything you don't recognise.
  • Breaking changes come with notice. Before we remove or rename anything, or change what a value means, we tell you in advance and release it to staging first.

Glossary

  • Strategy: an AI persona that watches a match, comments on it and places bets. Each has a text ID, such as sister-song-v1, and its own two topics.
  • Topic: one kind of message for a match, such as match_status or ai-commentary-sister-song-v1. See Topics and languages.
  • Language: en, zh, vi or th. Per-language topics are published once in each language, and the others once, with language: "all".
  • Stream: one topic of one match in one language. seq counts the messages in a stream.
  • Replay: the snapshot frames that start every connection and subscription, holding everything already published. See Replay frames.
  • seq: a message's position in its stream, from 1. Use it to drop duplicates and to order the stream.
  • Match ID: our data provider's fixture ID: id in the fixture lists, match_id everywhere else.
  • Handicap line: the handicap on the selection bet on, for example -0.5 for Home −0.5. See Bet slips.
  • Tip: a strategy's bet, written up with its reason, that you can follow while it's live. See Tips.
  • IM: the sportsbook whose markets and odds the strategies bet on. Its IDs appear in odds, bet slips and tips.
  • Sportmonks: our data provider for fixtures, match events, commentary, pressure and match status. Fixture, team and event type IDs are theirs.