API Command: get_connected_clients

The get_connected_clients command returns XML data containing details of all connected BeyondTrust clients.

The command API is an authenticated API. For instructions on using authenticated APIs using OAuth, please see Authenticate to the Privileged Remote Access API. The API account must have read-only or full access to the command API.

Required Parameters for get_connected_clients

type=[string] The types of clients to return in the results. Can be a comma-separated list of values. Supported values are all (default), representative, support_customer, presentation_attendee, and push_agent.
id=[string] The ID of the client. To get client IDs, see API Command: get_connected_client_list. Can be a comma-separated list of values. A maximum of 100 IDs is supported. This ID is a unique identifier which remains valid only while the client is connected.
include_connections=[boolean] If this is set to 1, then the client's list of connections to B Series Appliances and an event log about those connections will be included in the results.

XML Response for get_connected_clients

<connected_clients> Contains a child element for each connected client, including <connected_representative>, <connected_support_customer>, <connected_presentation_attendee>, and <connected_push_agent>.

Element Names and Attributes

/connected_clients/connected_representative
id (attribute) A unique identifier which remains valid only while the client is connected.
<client_connections> Contains a <client_connections> element and an <event_log> element. This element is returned only if the query specifies include_connections.
<hostname> The hostname of the representative’s computer.
<platform> The operating system of the representative’s computer. Also contains an id attribute that briefly notes the selected platform for the client.
<timezone_offset> The number of seconds away from UTC.
<connected_since> The date and time at which this connection was made. Data is returned in ISO 8601 format. Also contains a ts attribute which displays the connection start time as a UNIX timestamp (UTC). This element is returned only if the query specifies include_connections.
<user_id> Unique ID assigned to the representative.
<type> The type of account the representative is using. Can be one of Normal or Invited.
<username> The username assigned to the representative.
<public_display_name> The public display name assigned to the representative. Note that this field contains the public display name's value at the time of the conference, which may not match the current value if the public_display_name has subsequently been changed.
<private_display_name> The private display name assigned to the representative. Note that this field contains the private display name's value at the time of the conference, which may not match the current value if the private_display_name has subsequently been changed.
<start_session_url> A URL that can be sent to a customer to start a support session with the representative.
<presentation_count> The number of presentations the representative is performing. Can be either 0 or 1.
<support_session_count> The number of sessions the representative is participating in.
<showing_on_rep_list> Integer value (1 or 0) indicating if the representative appears in the representative list on the public site.
<routing_idle> Integer value (1 or 0) indicating if the representative has a status of idle.
<routing_busy> Integer value (1 or 0) indicating if the representative has a status of busy.
<routing_enabled> Integer value (1 or 0) indicating if the representative has automatic session assignment enabled or disabled.
<routing_available> Integer value (1 or 0) indicating if the representative is available to have sessions automatically assigned.
<support_license> The type of license used by the representative.
<support_session_lsids> Contains an <lsid> element for each session in which the representative is participating. This field corresponds with the <lsid> field of the <connected_support_customer> element.
/connected_clients/connected_support_customer
id (attribute) A unique identifier which remains valid only while the client is connected.
<client_connections> Contains a <client_connections> element and an <event_log> element. This element is returned only if the query specifies include_connections.
<hostname> The hostname of the customer’s computer.
<platform> The operating system of the customer’s computer. Also contains an id attribute that briefly notes the selected platform for the client.
<timezone_offset> The number of seconds away from UTC.
<connected_since> The date and time at which this connection was made. Data is returned in ISO 8601 format. Also contains a ts attribute which displays the connection start time as a UNIX timestamp (UTC). This element is returned only if the query specifies include_connections.
<name> The name which the customer entered in the Your Name field of the front-end survey or which was assigned programmatically.
<non_interactive> Indicates if the session is a remote desktop protocol (RDP) session or a Shell Jump session. Can be either rdp or shelljump. If neither, this element is not returned.
<lsid> A string which uniquely identifies this session. This field corresponds with the <lsid> field of the <connected_representative> element.
/connected_clients/connected_presentation_attendee
id (attribute) A unique identifier which remains valid only while the client is connected.
<client_connections> Contains a <client_connections> element and an <event_log> element. This element is returned only if the query specifies include_connections.
<hostname> The hostname of the attendee’s computer.
<platform> The operating system of the attendee’s computer. Also contains an id attribute that briefly notes the selected platform for the client.
<timezone_offset> The number of seconds away from UTC.
<connected_since> The date and time at which this connection was made. Data is returned in ISO 8601 format. Also contains a ts attribute which displays the connection start time as a UNIX timestamp (UTC). This element is returned only if the query specifies include_connections.
<name> The name which the attendee entered when joining the presentation or which was assigned programmatically.
/connected_clients/connected_push_agent
id (attribute) A unique identifier which remains valid only while the client is connected.
<client_connections> Contains a <client_connection> element and an <event_log> element. This element is returned only if the query specifies include_connections.
<hostname> The hostname of the Jumpoint’s host computer.
<platform> The operating system of the Jumpoint’s host computer. Also contains an id attribute that briefly notes the selected platform for the client.
<timezone_offset> The number of seconds away from UTC.
<connected_since> The date and time at which this connection was made. Data is returned in ISO 8601 format. Also contains a ts attribute which displays the connection start time as a UNIX timestamp (UTC). This element is returned only if the query specifies include_connections.
<name> The Jumpoint's name.
/client_connection
<appliance_id> The GUID of the B Series Appliance to which the client is connected.
<purpose> The reason the representative is connected to this B Series Appliance. Can be either primary or traffic. If not part of a cluster, this will always be primary.
<receive_traffic_node>

Integer value (1 or 0) indicating whether this is the client's default traffic node or not. If not part of a cluster, this will always be 0.

<connected_since> The date and time at which the client connected. Data is returned in ISO 8601 format. Also contains a ts attribute which displays the connection start time as a UNIX timestamp (UTC).
<private_ip> The client's private IP address that was used to connect to the B Series Appliance.
/event_log
<event>

An <event> element is created for each event that took place during this connection. Up to the last 20 events are returned.

Events detail when and why a client connected to a B Series Appliance. Events also include failures to connect to nodes and normal disconnects.

Includes a ts attribute which displays the timestamp of the event.

Query Examples: get_connected_clients

Get a detailed list of all connected clients

https://access.example.com/api/command?action=get_connected_clients

Get a detailed list of all connected representatives

https://access.example.com/api/command?action=get_connected_clients&type=representative

Get a detailed list of all connected representatives and support customers

https://access.example.com/api/command?action=get_connected_clients&type=representative,support_customer

Get a detailed list of all clients with IDs 101, 102, and 103

https://access.example.com/api/command?action=get_connected_clients&id=101,102,103

Get a detailed list of all clients with IDs 101, 102, and 103 AND whose type is representative or customer

https://access.example.com/api/command?action=get_connected_clients&id=101,102,103&type=representative,support_customer

Get a detailed list, with connection information, of all connected clients

https://access.example.com/api/command?action=get_connected_clients&include_connections=1

Get a detailed list, with connection information, of all connected representatives

https://access.example.com/api/command?action=get_connected_clients&type=representative&include_connections=1

Get a detailed list, with connection information, of all connected representatives and support customers

https://access.example.com/api/command?action=get_connected_clients&type=representative,support_customer&include_connections=1

Get a detailed list, with connection information, of all clients with IDs 101, 102, and 103

https://access.example.com/api/command?action=get_connected_clients&id=101,102,103&include_connections=1

Get a detailed list, with connection information, of all clients with IDs 101, 102, and 103 AND whose type is representative or customer

https://access.example.com/api/command?action=get_connected_clients&id=101,102,103&type=representative,support_customer&include_connections=1