Skip to main content
The Gateway API provides a REST surface for real-time state information about connected bots and gateway shards. For low-latency streaming events, use the Gateway WebSocket (not covered here). The REST endpoints are useful for polling current state.
Looking for the full API Reference? Visit api-docs.fnlb.net/gateway/ for our comprehensive interactive documentation.
Common use cases:
  • Show which bots are currently connected.
  • Display party members and presence status.
  • Inspect shard / cluster health and capacity.

​
Base URL

https://gateway.fnlb.net
All endpoints require a valid API key provided in the Authorization header using your FNLB API token. Learn more.
All requests must include the FNLB_BUCKET_ID query parameter using your FNLB account ID.
Example: https://gateway.fnlb.net/bots?FNLB_BUCKET_ID=62e542d92a56e7ebd885a9d2

​
Endpoints

​
GET /bots

Returns a list of currently connected bots. This endpoint is read-only and only includes bots with an active connection to the gateway (it does not list offline bots). Request 
GET https://gateway.fnlb.net/bots
Accept: application/json
Response (200 OK)
​
response
array
required
An array of connected bot objects.
Each bot object contains the most relevant public state fields. Common fields are documented below.
​
id
string
required
Unique identifier for the bot.
​
nickname
string
required
Nickname of the bot.
​
email
string
Email address associated with the bot account (where applicable).
​
status
number
required
Numeric status code describing connection state.
Offline: 0, Booting: 1, Available: 2, Busy: 3, Disconnected: 4
​
epicId
string
Epic account id.
​
friendsCount
number
Number of friends currently known for the bot.
​
presenceStatus
string
Short presence string that may include the custom status.
​
party
object
Party information when the bot is currently in a party. If the bot is not in a party this field may be omitted.
​
party.id
string
Party unique id.
​
party.playlistId
string
Optional playlist or game mode id for the party.
​
party.members
array
List of party members with their in-party metadata.
​
party.members[].id
string
required
Member account id.
​
party.members[].displayName
string
Member display name.
​
party.members[].outfit
string
Cosmetic outfit identifier for the member.
​
party.members[].backpack
string
Cosmetic backpack identifier.
​
party.members[].pickaxe
string
Cosmetic pickaxe/harvest tool identifier.
​
mmsBannedUntil
number
Optional timestamp (ms since epoch) when an matchmaking ban expires.
Example response (200) 
[
  {
    "id": "664c91348d12740f67776132",
    "nickname": "Alpha Bot",
    "email": "alpha-bot@example.com",
    "status": 1,
    "epicId": "66c4b21ecaed451e9f6444d3842954a2",
    "friendsCount": 5,
    "presenceStatus": "1/16 | BL | fnlb.net",
    "party": {
      "id": "a05e8408078e4df3b4ff366a0305a402",
      "playlistId": "Playlist_DefaultDuo",
      "members": [
        {
          "id": "e33a89ac51dc413a9414e3b941284bcf",
          "displayName": "Alpha",
          "outfit": "CID_434_Athena_Commando_F_StealthHonor",
          "backpack": "BID_138_Celestial",
          "pickaxe": "Pickaxe_ID_116_Celestial",
          "variants": {},
          "isReady": false,
          "isLeader": true,
          "isSittingOut": false,
          "isPlaying": false
        }
      ]
    }
  },
  {
    "id": "664c91348d12740f67776133",
    "nickname": "Beta Bot",
    "email": "beta-bot@example.com",
    "status": 2,
    "epicId": "66c4b21ecaed451e9f6444d3842954a3",
    "friendsCount": 0,
    "party": null
  }
]

​
GET /shards

Returns metadata about connected gateway shards (clusters). Useful for monitoring cluster capacity and which shard a bot is served from. Request 
GET https://gateway.fnlb.net/shards
Accept: application/json
Response (200 OK)
​
response
array
required
Array of shard status objects.
Common fields returned for each shard:
​
id
string
required
Shard unique identifier.
​
clusterId
string
required
Logical cluster id.
​
clusterName
string
Human-friendly cluster name.
​
version
string
Bot version running on the shard.
​
requestedBots
number
Number of bots requested/allocated to this shard.
​
connectedBots
number
required
Current number of connected bots on this shard.
​
categories
array
Optional array of category ids associated with the shard.
​
isOutdated
boolean
If true, the shard is running an older bot version.
​
isManaged
boolean
Whether this shard is VIP.
​
platform
string
OS/platform string (e.g. “Linux”).
​
appSource
string
The deployment source (e.g. “SelfHosted” or an internal name).
Example response (200) 
[
  {
    "id": "nXvJvQt5l02MITpMAAAb",
    "clusterId": "public-cluster",
    "clusterName": "Public Cluster",
    "version": "1.2.3",
    "requestedBots": 20,
    "connectedBots": 3,
    "categories": ["66c4b21ecaed451e9f6444d3842954a7"],
    "isManaged": false,
    "isOutdated": false,
    "platform": "Linux",
    "appSource": "SelfHosted"
  },
  {
    "id": "wGOaMRh3YZVf-J3CAANn",
    "clusterId": "vip-cluster",
    "clusterName": "VIP Cluster",
    "version": "1.2.3",
    "requestedBots": 10,
    "connectedBots": 0,
    "categories": ["66c4b21ecaed451e9f6444d3842954a7"],
    "isManaged": true,
    "isOutdated": false,
    "platform": "Linux",
    "appSource": "SelfHosted"
  }
]

​
Notes & Best Practices

  • These REST endpoints reflect currently connected state. They are useful for polling, for real-time events prefer the gateway WebSocket.
  • Keep polling intervals reasonable (10-30s).
Looking for the full API Reference? Visit api-docs.fnlb.net/gateway/ for our comprehensive interactive documentation.