List connected clients

Returns all open WebSocket connections of the application, including the current one. The list shows how many clients work with the application and which of them are subscribed to data. Use the uuid from the list to close a connection with connection_kill.

Find your own connection in the list by the uuid from the connected message the server sends on connect.

Request and response: connections_list → connections_list_resp.
Access: a token of any access level; the list contains only the connections of the application you are connected to.

Current ONS version

The server responds with connections_list_resp, not connections_list as stated in the v0.17 description.

Request

Fields not marked as required may be omitted.

Field	Type	Description
cmd	string	connections_list
operation_id	string	Any string; the server returns it in the response to match the request and the response

{
    "cmd": "connections_list",
    "operation_id": "abc"
}

Response

Field	Type	Description
cmd	string	connections_list_resp
operation_id	string	Value from the request
status	uint8	Always 1
connections	array	Open connections of the application, see below

A connections item:

Field	Type	Description
uuid	string	Connection identifier, 32 hex characters. The same as in connected
consume	bool	true — the connection is subscribed to data: with consume_req or automatically on connect
peer	string	Address and port the server accepted the connection from, as tcp4:address:port. If the server is behind a proxy, this is the proxy's address, not the client's

{
    "cmd": "connections_list_resp",
    "operation_id": "abc",
    "status": 1,
    "connections": [
        {
            "uuid": "80f0769cae484a4ea7a22a023f2f6379",
            "consume": true,
            "peer": "tcp4:172.20.0.1:56758"
        },
        {
            "uuid": "437dc414577d4efda7121e78849bfa7a",
            "consume": false,
            "peer": "tcp4:172.20.0.1:56770"
        }
    ]
}

Errors

The command has no error codes. If the server could not get the list, it sends invalid_command_req with your operation_id instead of connections_list_resp — retry later.

Good to know

• The list includes the application's connections from all server instances, while connection_kill finds only connections of the instance you are connected to. If ONS runs as several instances, not every connection from the list can be closed.
• consume shows the subscription to device data. The list does not show the subscription to downlink statuses (downlink_status).

See also

• connection_kill — close a connection by uuid.
• Connection — the connected message and the connection limit.