Feed Data Reference¶

Every update is one data_feed_update message carrying the current state of every machine in the feed, in the feed's order. You don't need to merge changes: each update replaces the last.

Update Message¶

{
  "type": "data_feed_update",
  "metadata": {
    "created_at": "2026-10-08T19:04:12.481Z",
    "updated_at": "2026-10-08T19:04:12.481Z"
  },
  "payload": {
    "machines": [
      {
        "machine_uuid": "3f6c1a2e-8b4d-4e1f-9a7c-2d5e6f708192",
        "game_name": "Monster Bash",
        "game_in_progress": true,
        "game_ended": false,
        "scores": [
          {
            "position": 1,
            "player": {
              "id": "9b2e4c61-0d3a-4f5b-8e7c-1a2b3c4d5e6f",
              "username": "pinwizard",
              "avatar": "https://cdn.example.com/avatars/abc.png",
              "display_name": "Pin Wizard",
              "initials": "PWZ"
            },
            "score": 48210330,
            "ball": 2,
            "ball_in_progress": true,
            "modes": ["MB:Multiball"],
            "is_nfc_verified": false,
            "tournament_id": null
          },
          {
            "position": 2,
            "player": null,
            "score": 1250000,
            "ball": null,
            "ball_in_progress": false,
            "modes": [],
            "is_nfc_verified": false,
            "tournament_id": null
          }
        ],
        "updated_at": "2026-10-08T19:04:11Z"
      }
    ]
  }
}

The values above are made up.

Message Fields¶

Field	Type	Meaning
`type`	string	Always `data_feed_update`
`metadata.created_at`, `metadata.updated_at`	ISO 8601 timestamp	When the message was produced
`metadata.game`, `.machine`, `.variant`, `.venue`	uuid, optional	Present only when set
`metadata.sequence`	integer, optional	Present only when set
`payload.machines`	array	Every machine the feed covers now, in feed order, including idle machines. May be empty on a feed that follows its venues

Machines¶

Field	Type	Meaning
`machine_uuid`	uuid	The machine. Use this as the key for anything you render
`game_name`	string, optional	The game title on the machine
`game_in_progress`	boolean	A game is being played. Both `game_in_progress` and `game_ended` are `false` on an idle machine
`game_ended`	boolean	The last game has finished and `scores` are its final scores
`scores`	array	One entry per player position in the current or last game
`updated_at`	timestamp or `null`, optional	When this machine's state last changed

Scores¶

Field	Type	Meaning
`position`	integer	Player position: 1 for player 1, and so on
`player`	object or `null`	Who is playing this position. `null` for an unclaimed slot
`score`	integer	The current score
`ball`	integer or `null`, optional	The ball being played. `null` when unavailable, which says nothing about whether a game is running
`ball_in_progress`	boolean or `null`, optional	This position's ball is in play
`modes`	array of strings	Game modes active for this position, for example `MB:Multiball`
`is_nfc_verified`	boolean	The player checked in with NFC at the machine
`tournament_id`	string or `null`, optional	The tournament this game belongs to; `null` for casual play

Players and Privacy¶

Field	Type	Meaning
`username`	string	The player's Scorbit username
`display_name`	string, optional	The name to show, when available
`initials`	string, optional	The player's initials, for example `PWZ`
`avatar`	URL or `null`, optional	The player's avatar image
`id`	uuid, optional	The player's Scorbit user id

Player information appears only for players who claimed their position. Treat everything in player as personal data. The Developer Terms require you to:

show player information only in the form the feed delivers it;
never try to identify an anonymous player;
stop showing a player once they drop out of the feed;
keep player data no longer than your integration needs, and never longer than 30 days.

Machines Joining and Leaving¶

On a feed opened without naming machines, using a venue-scoped key, the feed follows its venues: machines join and leave as the venues change, and the set can become empty without the feed ending.

Every update carries the current machine list, and it is authoritative: key what you render by machine_uuid, never by position.
The library emits a machines event, { added, removed, machines }, before the update that carries the change. The agent sends the same as a machines event on /events.

Any other feed, one opened with a list of machines or with a machine-scoped key, is fixed: it ends if one of its machines leaves the account.