Gateway control

Gateway control is the Admin view of the running main Gateway cluster. It reads live node state and submits guild reload requests, and it exposes no session, presence, or call payload.

An unanswered Gateway request returns 504 GATEWAY_TIMEOUT. An overloaded or unavailable cluster returns 503 SERVICE_UNAVAILABLE. An invalid Gateway response returns 502 BAD_GATEWAY.

Every value is live state

The Gateway cluster answers each read at request time. Two consecutive reads can differ without any Admin action, and a node that is restarting can be absent from one response and present in the next.

Node statistics object

One snapshot of the Gateway cluster, taken across the nodes the request polled. Every top-level counter except uptime_seconds, node_count, and status is a plain sum over those nodes, including each member of memory. The nodes array reports each polled node on its own.

Structure

Field	Type	Description
status1	string	The aggregate health of the cluster
sessions	integer	The connected client Gateway sessions, summed across nodes
guilds	integer	The live guild processes, summed across nodes
presences	integer	The tracked presences, summed across nodes
calls	integer	The live calls, summed across nodes
memory	node memory object	The memory accounting, summed across nodes
process_count	integer	The Erlang processes in use, summed across nodes
process_limit	integer	The Erlang process ceiling, summed across nodes
uptime_seconds2	integer	The lowest uptime any polled node reported, in seconds
node_count3	integer	The number of nodes the request polled
nodes4	array[gateway node object]	The per-node breakdown (max 1000 entries)

¹ healthy when every polled node reported healthy and degraded when at least one did not

² The value tracks the most recently started node and drops back whenever any node restarts

³ Includes nodes that did not answer

⁴ Entries are ordered by node_id ascending. The node that served the request is always polled, so the array is never empty

Example

{
  "status": "healthy",
  "sessions": 4820,
  "guilds": 1913,
  "presences": 4611,
  "calls": 12,
  "memory": {"total": "3221225472", "processes": "1610612736", "system": "1610612736"},
  "process_count": 92114,
  "process_limit": 2097152,
  "uptime_seconds": 84213,
  "node_count": 2,
  "nodes": []
}

Gateway node object

One entry for each node the request polled, including nodes that did not answer within the 10 second per-node deadline.

Structure

Field	Type	Description
node_id1	string	The name the node reports for itself
status2	string	The health this node reported
sessions	integer	The connected client Gateway sessions on this node
guilds	integer	The live guild processes on this node
presences	integer	The tracked presences on this node
calls	integer	The live calls on this node
memory	node memory object	The memory accounting for this node
process_count	integer	The Erlang processes in use on this node
process_limit	integer	The Erlang process ceiling on this node
uptime_seconds	integer	The seconds since this node started

¹ A node reports its HOSTNAME environment value when that value is a non-blank string, and its Erlang node name otherwise

² healthy for a node that answered and unavailable for one that did not. A node that did not answer reports null for every counter here and contributes zero to every cluster total

A node entry can have further diagnostic members. A client treats a member it does not recognise as absent.

Node memory object

Byte counts for one node, or for every polled node summed together. Each count is a decimal string because a JSON number cannot preserve a 64-bit byte count.

Structure

Field	Type	Description
total	string	The total bytes allocated
processes	string	The bytes allocated to Erlang processes
system	string	The bytes allocated outside Erlang processes

Guild memory statistics object

Memory and activity for one live guild.

Structure

Field	Type	Description
node_id	string	The node that owns the guild process
guild_id	?snowflake	The ID of the guild the process serves, or null when the process state has no guild ID
guild_name1	string	The guild name the process holds in memory
guild_icon	?string	The icon hash the guild process holds in memory, or null when it has none
nsfw_level2	?integer	The NSFW level resolved from stored guild data, or null when the guild could not be resolved
memory3	string	The bytes the guild process uses, as a decimal string
member_count	integer	The number of members the guild process holds
session_count	integer	The number of sessions subscribed to the guild process
presence_count	integer	The number of presences the guild process tracks

¹ A process whose cached guild data has no name reports Unknown

² Null for a live process whose guild row could not be loaded and for a process that reports no guild_id

³ The Erlang process memory of the guild process. Entries are ordered by it descending across the whole cluster, with ties broken by guild_id ascending

Voice state count object

Cluster voice state totals, with one grouping by voice region and one by voice server.

Structure

Field	Type	Description
total_voice_states1	integer	The voice states across the whole cluster
regions2	array[region voice state count object]	The counts grouped by voice region (max 1000 entries)
servers2	array[server voice state count object]	The counts grouped by voice server (max 5000 entries)

¹ The sum of the totals each node reported, so it can differ from the sum of the entries in regions or servers

² Entries are ordered by voice_state_count descending, with ties broken by identifier ascending. An identifier with no voice states is absent from the array, so every entry has a count of at least 1

Example

{
  "total_voice_states": 318,
  "regions": [{"region_id": "europe-north", "voice_state_count": 204}],
  "servers": [{"server_id": "europe-north-server-1", "voice_state_count": 204}]
}

Region voice state count object

One entry for each voice region that holds at least one voice state.

Structure

Field	Type	Description
region_id	string	The ID of the region the count belongs to
voice_state_count	integer	The voice states attributed to the region

Server voice state count object

One entry for each voice server that holds at least one voice state.

Structure

Field	Type	Description
server_id1	string	The ID of the server the count belongs to
voice_state_count	integer	The voice states attributed to the server

¹ The identifier is unique only inside its region

Get Gateway node statistics

GET/v1/admin/gateway/statsAudit reason

Returns the node statistics object for the whole Gateway cluster. Requires gateway:memory_stats.

Response

Status	Body	Condition
200	node statistics object	Cluster state was returned

Side effects

The operation records one Admin audit entry with action get_gateway_stats, target type gateway, target ID 0, and metadata key node_count.

Rate limit

200 requests per minute for each authenticated user, on the admin:lookup bucket.

Get guild memory statistics

GET/v1/admin/gateway/memory-statsAudit reason

Returns the heaviest live guild processes as guild memory statistics objects. Requires gateway:memory_stats.

Query parameters

Field	Type	Description
limit?1	integer	The maximum guild processes to return (100-1000, default 100)

¹ The Gateway clamps the value it acts on to 500, and each node contributes at most 100 of its own guild processes. A limit of 1000 returns at most 500 entries

Response body

Field	Type	Description
guilds	array[guild memory statistics object]	The guild processes in this response (max 1000 entries)

Response

Status	Body	Condition
200	response body	The guild processes were returned

Side effects

A node that does not answer within 5 seconds contributes no entries, and the request still returns 200.

The operation records one Admin audit entry with action list_guild_memory_stats, target type guild, target ID 0, and metadata keys limit and result_count for the entries in this response.

Rate limit

200 requests per minute for each authenticated user, on the admin:lookup bucket.

Get voice state counts

GET/v1/admin/gateway/voice-state-countsAudit reason

Returns the voice state count object. Requires gateway:memory_stats.

Response

Status	Body	Condition
200	voice state count object	Counts were returned

Side effects

The counts cover voice states in guild channels and in calls. A node that does not answer within 10 seconds contributes zero, and the request still returns 200.

The operation records one Admin audit entry with action get_voice_state_counts, target type gateway, target ID 0, and metadata keys total_voice_states, region_count, and server_count.

Rate limit

200 requests per minute for each authenticated user, on the admin:lookup bucket.

Reload Gateway guilds

POST/v1/admin/gateway/reloadsAudit reason

Fetches the guild data for the supplied guilds from the database again and sends it to each live guild process and returns how many live guild processes were selected. Requires gateway:reload_all.

JSON body

Field	Type	Description
guild_ids1	array[snowflake]	The guilds to reload (max 1000 entries)

¹ The field is required. An empty array selects every live guild process on every active node

An empty array reloads the whole cluster

Sending {"guild_ids": []} dispatches a reload to every live guild process on every active node. Send an explicit list unless a cluster-wide reload is intended.

A reload fires Guild Update

Every reloaded guild process fires one Guild Update Dispatch to each session subscribed to it. The payload is the rebuilt guild.

Response body

Field	Type	Description
count1 2	integer	The number of live guild processes selected for reload

¹ A supplied guild with no live process is skipped, so the value can be lower than the number of IDs sent. An owner node that fails or does not answer within 15 seconds contributes zero

² Taken when the processes are selected. A selected process whose guild data cannot be fetched is still counted, so the value is an upper bound on the reloads that succeeded

Response

Status	Body	Condition
200	response body	FiveCord started a reload for every selected guild process

Side effects

A guild whose owner node cannot be resolved is not counted. Reloads can still be in progress when the response arrives. No guild data is changed.

The operation records one Admin audit entry with action reload_guilds, target type guild, target ID 0, and metadata keys guild_count for the requested guilds and reloaded for the returned count.

Rate limit

5 requests per minute for each authenticated user, on the admin:gateway:reload bucket.