Get Machine V4

At least one of the listed privileges is required -

Privileges	Description
MACHINE_VIEW	Caller should have permission to this privilege, on the associated access group of machine's desktop pool.
GLOBAL_CONFIG_VIEW	Caller should have permission to this privilege to read the unmanaged (physical) machines that are part of desktop pool.

Request

URI

GET

https://{api_host}/rest/inventory/v4/machines/{id}

COPY

Path Parameters

string

Required

Authentication

This operation uses the following authentication methods.

Bearer

Responses

200

Returns MachineInfoV4 of type(s) */*

{
    "access_group_id": "6fd4638a-381f-4518-aed6-042aa3d9f14c",
    "agent_build_number": "22673015",
    "agent_upgrade_error_message": "true",
    "agent_upgrade_result": "OK",
    "agent_upgrade_state": "WAIT",
    "agent_version": "7.12",
    "aliases": [
        {
            "ad_user_id": "S-1-5-21-2898529287-1016622242-505487308-1553",
            "alias_name": "Alias1"
        }
    ],
    "attempted_theft_by_connection_server": [
        "connection-server2.example.com"
    ],
    "configured_by_connection_server": [
        "connection-server1.example.com"
    ],
    "desktop_pool_id": "855ea6c5-720a-41e1-96f4-958c90e6e424",
    "dns_name": "machine1.example.com",
    "held_machine": true,
    "id": "0103796c-102b-4ed3-953f-3dfe3d23e0fe",
    "managed_machine_data": {
        "base_vm_id": "vm-23",
        "base_vm_snapshot_id": "snapshot-2",
        "clone_error_message": "Timeout expired trying to clone a virtual machine.",
        "clone_error_time": 1575285661395,
        "create_time": 1575285661395,
        "datastore_ids": [
            "datastore1",
            "datastore2"
        ],
        "host_name": "WD332H5",
        "image_management_stream_id": "6f85b3a5-e7d0-4ad6-a1e3-37168dd1ed51",
        "image_management_tag_id": "c9896e51-48a2-4d82-ae9e-a0246981b47d",
        "in_hold_customization": false,
        "in_maintenance_mode": false,
        "last_maintenance_time": 1587081283000,
        "logoff_policy": "FORCE_LOGOFF",
        "memory_mb": 1024,
        "missing_in_vcenter": false,
        "network_labels": [
            {
                "network_label_name": "example-network",
                "nic_name": "network1"
            }
        ],
        "operation": "REFRESH",
        "operation_state": "AVAILABLE",
        "path": "/path/host",
        "pending_base_vm_id": "vm-8",
        "pending_base_vm_snapshot_id": "snapshot-7",
        "pending_image_management_stream_id": "ec88b3a5-e7d0-4ad6-a1e3-37168dd1fa25",
        "pending_image_management_tag_id": "c9896e51-48a2-4d82-ae9e-a0246981b47d",
        "storage_accelerator_state": "CURRENT",
        "virtual_center_id": "0103796c-102b-4ed3-953f-3dfe3d23e0fe",
        "virtual_disks": [
            {
                "capacity_mb": 102400,
                "datastore_path": "datastore1",
                "path": "/path/host"
            }
        ],
        "virtual_machine_power_state": "POWERED_ON"
    },
    "message_security_enhanced_mode_supported": true,
    "message_security_mode": "MIXED",
    "name": "machine1",
    "operating_system": "WINDOWS_SERVER_2016",
    "operating_system_architecture": "BIT_64",
    "pairing_state": "IN_PAIRING",
    "remote_experience_agent_build_number": "32573985",
    "remote_experience_agent_version": "7.12",
    "session_id": "6fd4638a-381f-4518-aed6-042aa3d9f14c",
    "state": "PROVISIONING",
    "type": "MANAGED_MACHINE",
    "user_ids": [
        "S-1-1-1-3965912346-1012345398-3123456564-123",
        "S-1-2-3-3123456786-1012345398-3123456784-124"
    ]
}

string

access_group_id

Optional

Access group id of this Machine.

string

agent_build_number

Optional

The Horizon Agent build number.
Supported Filters : 'Equals'. This property can be used for sorting.

string

agent_upgrade_error_message

Optional

Error message of the agent upgrade operation failure on the machine. This property can be used for sorting.

string

agent_upgrade_result

Optional

Result of the agent upgrade operation on the machine. This property can be used for sorting.

DUPLICATE: Agent received duplicate upgrade request.
ERROR: Agent upgrade has unknown error.
FAILURE: Agent upgrade has failed.
INVALID: Agent received invalid values for upgrade.
NOT_FOUND: Agent could not find upgrade request.
OK: Agent upgrade is OK.
PREFLIGHTCHECK_FAILURE: Preflight check failed for agent upgrade.
PREFLIGHTCHECK_INPROGRESS: Preflight check is in progress for agent upgrade.
PREFLIGHTCHECK_OK: Preflight check succeeded for agent upgrade.
PROGRESS: Agent upgrade is in progress.
UNKNOWN: Agent upgrade result is unknown.

Possible values are : DUPLICATE, ERROR, FAILURE, INVALID, NOT_FOUND, OK, PREFLIGHTCHECK_FAILURE, PREFLIGHTCHECK_INPROGRESS, PREFLIGHTCHECK_OK, PROGRESS, UNKNOWN,

string

agent_upgrade_state

Optional

State of the agent upgrade operation on the machine. This property can be used for sorting.

DONE: Agent upgrade task has ended.
DOWNLOAD: Agent is downloading the upgrade binary.
NOLOGON: Agent has no logged in user.
READY: Agent is ready to be upgraded.
UNKNOWN: Agent upgrade state is unknown.
UPDATING: Agent is upgrading.
WAIT: Agent is waiting for user to logoff or for reboot to complete.

Possible values are : DONE, DOWNLOAD, NOLOGON, READY, UNKNOWN, UPDATING, WAIT,

string

agent_version

Optional

The Horizon Agent version.
Supported Filters : 'Equals'. This property can be used for sorting.

array of object

aliases

Optional

List of MachineAlias

array of string

attempted_theft_by_connection_server

Optional

Names of the Horizon Connection Servers that attempted theft of pairing for this Agent.

array of string

configured_by_connection_server

Optional

Names of the Horizon Connection Servers the Horizon Agent is paired with.

string

desktop_pool_id

Optional

The id of the Desktop Pool that the machine belongs to.
Supported Filters : 'Equals'.

string

dns_name

Optional

DNS name of the machine.
Supported Filters : 'Equals', 'StartsWith', 'EndsWith' and 'Contains'. This property can be used for sorting.

boolean

held_machine

Optional

Indicates whether the machine is in held state.Supported Filters: 'Equals'. This property can be used for sorting.

string

Optional

Unique ID representing machine.
Supported Filters : 'Equals'.

object

managed_machine_data

Optional

Information related to Managed machines V2.

boolean

message_security_enhanced_mode_supported

Optional

Indicates whether ENHANCED message security mode is currently supported by this machine.

string

message_security_mode

Optional

The current JMS message security mode used by this machine.
Supported Filters : 'Equals'. This property can be used for sorting.

DISABLED: Message security mode is disabled.
ENABLED: Message security mode is enabled. Unsigned messages are rejected by Horizon components.
ENHANCED: Message Security mode is Enhanced. Message signing and validation is performed based on the current Security Level and desktop Message Security mode.
MIXED: Message security mode is enabled but not enforced.

Possible values are : DISABLED, ENABLED, ENHANCED, MIXED,

string

name

Optional

Name of the machine.
Supported Filters : 'Equals', 'StartsWith' and 'Contains'. This property can be used for sorting.

string

operating_system

Optional

The guest operating system. This property can be used for sorting.

LINUX_CENTOS: Linux (CentOS)
LINUX_OTHER: Linux (other)
LINUX_RHEL: Linux (Red Hat Enterprise)
LINUX_SERVER_OTHER: Linux server (other)
LINUX_SUSE: Linux (Suse)
LINUX_UBUNTU: Linux (Ubuntu)
UNKNOWN: Unknown
WINDOWS_10: Windows 10
WINDOWS_11: Windows 11
WINDOWS_7: Windows 7
WINDOWS_8: Windows 8
WINDOWS_SERVER_2003: Windows Server 2003
WINDOWS_SERVER_2008: Windows Server 2008
WINDOWS_SERVER_2008_R2: Windows Server 2008 R2
WINDOWS_SERVER_2012: Windows Server 2012
WINDOWS_SERVER_2012_R2: Windows Server 2012 R2
WINDOWS_SERVER_2016_OR_ABOVE: Windows Server 2016 or above
WINDOWS_VISTA: Windows Vista
WINDOWS_XP: Windows XP

Possible values are : LINUX_CENTOS, LINUX_OTHER, LINUX_RHEL, LINUX_SERVER_OTHER, LINUX_SUSE, LINUX_UBUNTU, UNKNOWN, WINDOWS_10, WINDOWS_11, WINDOWS_7, WINDOWS_8, WINDOWS_SERVER_2003, WINDOWS_SERVER_2008, WINDOWS_SERVER_2008_R2, WINDOWS_SERVER_2012, WINDOWS_SERVER_2012_R2, WINDOWS_SERVER_2016_OR_ABOVE, WINDOWS_VISTA, WINDOWS_XP,

string

operating_system_architecture

Optional

The guest operating system architecture.

UNKNOWN: Operating System cannot be determined.
BIT_32: 32 bit Operating System Architecture.
BIT_64: 64 bit Operating System Architecture.

Possible values are : UNKNOWN, BIT_32, BIT_64,

string

pairing_state

Optional

Horizon Agent pairing state.

NOT_AVAILABLE: Agent pairing state is not available.
IN_PAIRING: Agent pairing with Horizon Connection Server is in progress.
PAIRED_AND_SECURED: Agent is paired and secured with a Horizon Connection Server.

Possible values are : NOT_AVAILABLE, IN_PAIRING, PAIRED_AND_SECURED,

string

remote_experience_agent_build_number

Optional

The remote experience Horizon Agent build number.
Supported Filters : 'Equals'. This property can be used for sorting.

string

remote_experience_agent_version

Optional

The remote experience Horizon Agent version.
Supported Filters : 'Equals'. This property can be used for sorting.

string

session_id

Optional

The ID of the session on the Machine (if one exists).

string

state

Optional

The state of the machine.
Supported Filters : 'Equals'. This property can be used for sorting.

AGENT_CONFIG_ERROR: The Remote Desktop Services role is not enabled on the windows server.
AGENT_DRAIN_MODE: RDS host is configured for drain mode. New connections are currently disabled.
AGENT_DRAIN_UNTIL_RESTART: RDS host is configured for drain-until-restart mode.
AGENT_ERROR_DISABLED: Horizon Agent is disabled.
AGENT_ERROR_INVALID_IP: Horizon Agent has an invalid IP address.
AGENT_ERROR_NEEDS_REBOOT: Horizon Agent needs reboot.
AGENT_ERROR_PROTOCOL_FAILURE: Protocol such as BLAST, RDP or PCoIP is not enabled.
AGENT_ERROR_STARTUP_IN_PROGRESS: Horizon Agent has started on the machine, but other required services such as the display protocol are still starting.
AGENT_ERROR_DOMAIN_FAILURE: The Remote Desktop Services domain failure.
AGENT_UNREACHABLE: Horizon Connection Server cannot establish communication with Horizon Agent on the machine.
ALREADY_USED: The machine is configured to have only one session which is currently in progress and cannot accept new sessions.
AVAILABLE: The machine is powered on and ready for active connections.
BLOCKED_AGENT_VERSION: The Horizon Agent version is blocked from establishing sessions.
CONNECTED: The machine is in an active session and has an active connection to a Horizon client.
CUSTOMIZING: The machine which is from an automated desktop pool is being customized after provisioning.
DELETING: The machine is marked for deletion.
DISABLED: The machine is disabled.
DISABLE_IN_PROGRESS: Disabled Horizon Connection Server still has some Horizon brokered sessions. It can still accept re-connections.
DISCONNECTED: The machine is in an active session, but it is disconnected from the Horizon client.
ERROR: An unknown error occurred in the machine.
IN_PROGRESS: There is a machine operation in progress.
MAINTENANCE: The machine is in maintenance mode. Users cannot log in or use the machine.
PROVISIONED: The machine is powered off or suspended.
PROVISIONING: The machine is being provisioned.
PROVISIONING_ERROR: An error occurred during provisioning.
UNASSIGNED_USER_CONNECTED: A user other than the assigned user is logged in to the machine in a dedicated desktop pool.
UNASSIGNED_USER_DISCONNECTED: A user other than the assigned user is logged in and disconnected from the machine in a dedicated desktop pool.
UNKNOWN: Could not determine the state of the machine.
VALIDATING: The Horizon Connection Server is synchronizing state information with the agent.
WAITING_FOR_AGENT: Horizon Connection Server is waiting to establish communication with Horizon Agent for one of these cases - a virtual machine in a manual desktop pool, unmanaged machine or RDS server.

Possible values are : AGENT_CONFIG_ERROR, AGENT_DRAIN_MODE, AGENT_DRAIN_UNTIL_RESTART, AGENT_ERROR_DISABLED, AGENT_ERROR_INVALID_IP, AGENT_ERROR_NEEDS_REBOOT, AGENT_ERROR_PROTOCOL_FAILURE, AGENT_ERROR_STARTUP_IN_PROGRESS, AGENT_ERROR_DOMAIN_FAILURE, AGENT_UNREACHABLE, ALREADY_USED, AVAILABLE, BLOCKED_AGENT_VERSION, CONNECTED, CUSTOMIZING, DELETING, DISABLED, DISABLE_IN_PROGRESS, DISCONNECTED, ERROR, IN_PROGRESS, MAINTENANCE, PROVISIONED, PROVISIONING, PROVISIONING_ERROR, UNASSIGNED_USER_CONNECTED, UNASSIGNED_USER_DISCONNECTED, UNKNOWN, VALIDATING, WAITING_FOR_AGENT,

string

type

Optional

The type of machine.
Supported Filters : 'Equals'. This property can be used for sorting.

MANAGED_MACHINE: The machine is a managed virtual machine.
UNMANAGED_MACHINE: The machine is an unmanaged physical or virtual machine.

Possible values are : MANAGED_MACHINE, UNMANAGED_MACHINE,

array of string

user_ids

Optional

The unique SIDs of the users assigned to the machine.
Supported Filters : 'Equals', 'NotEquals' and 'Contains'.

401

User is not authenticated

Operation doesn't return any data structure

403

Access to the resource is forbidden

Operation doesn't return any data structure

404

Not Found

Operation doesn't return any data structure

Code Samples

COPY

                    curl -H 'Authorization: <value>' https://{api_host}/rest/inventory/v4/machines/{id}

On This Page

Description

Request

Path Parameters

Authentication

Response

200 Response Body

Errors

Inventory Operations