Developer Documentation

Citrix Monitor Service API

How to retrieve data related to machine

September 12, 2024

Contributed by:

Machine represent the machine in the Site. Use Citrix Monitor Service API to get the data for entity machine.

Prerequisites

Read the Get started with Citrix Cloud APIs section to ensure that you have the bearer token.
Use the endpoint https://{ApiGatewayEndpoint}/monitorodata/Machines, for your region specific API gateway endpoint, see Supported API Gateway endpoints.
Invoke the API described in this document from a client host.

Active machines with count

LifecycleState value 0 represents Active machines.
$count=true parameter returns count in response.

Request

GET /monitorodata/Machines?$filter=LifecycleState eq 0&$count=true HTTP/1.1
Host: api.cloud.com
Authorization: CWSAuth bearer=<Token>
Citrix-CustomerId: <CustomerId>
<!--NeedCopy-->

Response

HTTP/1.1 200 OK
Date: Thu, 01 Aug 2024 06:23:00 GMT
Content-Type: application/json; odata.metadata=minimal
Content-Length: 5506
Connection: keep-alive
odata-version: 4.0

{
    "@odata.context": "https://api.cloud.com/monitorodata/$metadata#Machines",
    "@odata.count": 517,
    "value": [
        {
            "Id": "17f8b8f5-0f27-4852-a399-00194801a283",
            "Sid": "S-1-5-21-1924580635-3864722089-3907235813-107439",
            "Name": "ENG\\ra-s19-cvad036",
            "DnsName": "ra-s19-cvad036.eng.citrite.net",
            "LifecycleState": 0,
            "IPAddress": null,
            "HostedMachineId": "ccf63697-723c-0845-17fe-ebe1e2e75d31",
            "HostingServerName": "ra-xen-07",
            "HostedMachineName": "ra-s19-cvad036",
            "IsAssigned": false,
            "IsInMaintenanceMode": false,
            "IsPendingUpdate": false,
            "AgentVersion": "2212.0.0.77",
            "AssociatedUserFullNames": "",
            "AssociatedUserNames": "",
            "AssociatedUserUPNs": "",
            "CurrentRegistrationState": 2,
            "RegistrationStateChangeDate": "2024-08-05T22:03:08.31Z",
            "LastDeregisteredCode": 0,
            "LastDeregisteredDate": "2024-08-05T22:02:33.64Z",
            "CurrentPowerState": 2,
            "CurrentSessionCount": 0,
            "ControllerDnsName": "A21828-46-2.prodcp5.local",
            "PoweredOnDate": "2024-08-05T10:01:50.4Z",
            "PowerStateChangeDate": "2024-08-05T22:03:08.31Z",
            "FunctionalLevel": 10,
            "FailureDate": null,
            "WindowsConnectionSetting": 0,
            "IsPreparing": false,
            "FaultState": 1,
            "OSType": "Windows 2019",
            "CurrentLoadIndexId": 17863392,
            "CatalogId": "11c5298e-4516-4c1b-b83a-efb219009b71",
            "DesktopGroupId": "ad9e2d3d-44ac-49b0-a34b-7affb5ce3596",
            "HypervisorId": "56ac3d9f-2691-4d2c-aacb-95726611fe79",
            "LastPowerActionType": 3,
            "LastPowerActionReason": 8,
            "LastPowerActionFailureReason": 400,
            "LastPowerActionCompletedDate": "2024-08-05T22:02:50.887Z",
            "Tags": [],
            "Hash": "",
            "MachineRole": 0,
            "CreatedDate": "2020-06-10T14:31:36.183Z",
            "ModifiedDate": "2024-08-05T22:47:00.103Z"
        }
    ]
}
<!--NeedCopy-->

Machines in failure state

FailureDate is null represents the machine is not in a failure state.
FailureDate ne null represents the machine is in a failure state.
FailureDate ge 2024-07-30T00:00:00Z in $filter operation to get the machines in a failure state after 2024-07-30T00:00:00Z.

Request

GET /monitorodata/Machines?null=null&$filter=FailureDate ne null and FailureDate ge 2024-07-30T00:00:00Z HTTP/1.1
Host: api.cloud.com
Authorization: CWSAuth bearer=<Token>
Citrix-CustomerId: <CustomerId>
<!--NeedCopy-->

Response

HTTP/1.1 200 OK
Date: Thu, 01 Aug 2024 06:23:00 GMT
Content-Type: application/json; odata.metadata=minimal
Content-Length: 5506
Connection: keep-alive
odata-version: 4.0

{
    "@odata.context": "https://api.cloud.com/monitorodata/$metadata#Machines",
    "value": [
        {
            "Id": "70fe7ae3-e933-4f99-aabf-07153c261ee7",
            "Sid": "S-1-5-21-1924580635-3864722089-3907235813-416405",
            "Name": "ENG\\ra-w10-cvad008",
            "DnsName": "ra-w10-cvad008.eng.citrite.net",
            "LifecycleState": 0,
            "IPAddress": null,
            "HostedMachineId": "17934eda-3307-16a1-a7ee-0594d5f65a89",
            "HostingServerName": "ra-xen-07",
            "HostedMachineName": "ra-w10-cvad008",
            "IsAssigned": false,
            "IsInMaintenanceMode": false,
            "IsPendingUpdate": false,
            "AgentVersion": "2203.0.0.33220",
            "AssociatedUserFullNames": "",
            "AssociatedUserNames": "",
            "AssociatedUserUPNs": "",
            "CurrentRegistrationState": 2,
            "RegistrationStateChangeDate": "2024-07-30T23:49:47.18Z",
            "LastDeregisteredCode": 207,
            "LastDeregisteredDate": "2024-07-30T23:49:47.187Z",
            "CurrentPowerState": 3,
            "CurrentSessionCount": 0,
            "ControllerDnsName": "A21828-46-1.prodcp5.local",
            "PoweredOnDate": "2024-07-30T23:35:33.757Z",
            "PowerStateChangeDate": "2024-07-31T23:45:16.86Z",
            "FunctionalLevel": 9,
            "FailureDate": "2024-07-30T23:49:47.18Z",
            "WindowsConnectionSetting": 0,
            "IsPreparing": false,
            "FaultState": 4,
            "OSType": "Windows 10",
            "CurrentLoadIndexId": 17863154,
            "CatalogId": "8979ff21-701b-4cf6-bb3f-18a77cf46427",
            "DesktopGroupId": "87f4c976-b8f8-4b0e-82c3-dcd7f94c3661",
            "HypervisorId": "56ac3d9f-2691-4d2c-aacb-95726611fe79",
            "LastPowerActionType": 3,
            "LastPowerActionReason": 8,
            "LastPowerActionFailureReason": 401,
            "LastPowerActionCompletedDate": "2024-07-31T23:45:16.827Z",
            "Tags": [],
            "Hash": "",
            "MachineRole": 0,
            "CreatedDate": "2022-09-28T18:16:45.633Z",
            "ModifiedDate": "2024-07-31T23:47:00.173Z"
        }
    ]
}
<!--NeedCopy-->

MachineFailure details

Use $expand operation to get the details of MachineFailures.

Request

GET /monitorodata/Machines?$filter=FailureDate ne null and FailureDate ge 2024-07-30T00:00:00Z&$select=Id&$expand=MachineFailures($filter=FailureStartDate ge 2024-07-30T00:00:00Z) HTTP/1.1
Host: api.cloud.com
Authorization: CWSAuth bearer=<Token>
Citrix-CustomerId: <CustomerId>
<!--NeedCopy-->

Response

HTTP/1.1 200 OK
Date: Thu, 01 Aug 2024 06:23:00 GMT
Content-Type: application/json; odata.metadata=minimal
Content-Length: 5506
Connection: keep-alive
odata-version: 4.0

{
    "@odata.context": "https://api.cloud.com/monitorodata/$metadata#Machines(Id,MachineFailures())",
    "value": [
        {
            "Id": "70fe7ae3-e933-4f99-aabf-07153c261ee7",
            "MachineFailures": [
                {
                    "Id": 1589020,
                    "MachineId": "70fe7ae3-e933-4f99-aabf-07153c261ee7",
                    "FailureStartDate": "2024-07-30T11:13:43.04Z",
                    "FailureEndDate": "2024-07-30T23:34:55.38Z",
                    "FaultState": 4,
                    "LastDeregisteredCode": 207,
                    "CreatedDate": "2024-07-30T11:13:54.95Z",
                    "ModifiedDate": "2024-07-30T23:34:59.7Z"
                },
                {
                    "Id": 1589059,
                    "MachineId": "70fe7ae3-e933-4f99-aabf-07153c261ee7",
                    "FailureStartDate": "2024-07-30T23:49:47.18Z",
                    "FailureEndDate": null,
                    "FaultState": 4,
                    "LastDeregisteredCode": 207,
                    "CreatedDate": "2024-07-30T23:49:49.517Z",
                    "ModifiedDate": "2024-07-30T23:49:49.517Z"
                }
            ]
        }
    ]
}
<!--NeedCopy-->

Alive sessions on each machine

Sessions in $expand operation to get the sessions on this machine.
EndDate eq null represents the session is still alive.

GET /monitorodata/Machines?$select=Name,IsInMaintenanceMode,CurrentRegistrationState,CurrentSessionCount,IsPreparing,FaultState&$expand=DesktopGroup($select=Id,Name),Sessions($select=SessionKey,ConnectionState;$filter=EndDate+eq+null)&$filter=Name+ne+null+and+DesktopGroup+ne+null HTTP/1.1
Host: api.cloud.com
Authorization: CWSAuth bearer=<Token>
Citrix-CustomerId: <CustomerId>
<!--NeedCopy-->

HTTP/1.1 200 OK
Date: Thu, 01 Aug 2024 08:00:05 GMT
Content-Type: application/json; odata.metadata=minimal
Content-Length: 122546
Connection: keep-alive
odata-version: 4.0

{
    "@odata.context": "https://api.cloud.com/monitorodata/$metadata#Machines(Name,IsInMaintenanceMode,CurrentRegistrationState,CurrentSessionCount,IsPreparing,FaultState,DesktopGroup(Id,Name),Sessions(SessionKey,ConnectionState))",
    "value": [
        {
            "Name": "ENG\\ra-s19-cvad079",
            "IsInMaintenanceMode": false,
            "CurrentRegistrationState": 1,
            "CurrentSessionCount": 1,
            "IsPreparing": false,
            "FaultState": 1,
            "DesktopGroup": {
                "Id": "ad9e2d3d-44ac-49b0-a34b-7affb5ce3596",
                "Name": "CVD\\BUR CVAD Development"
            },
            "Sessions": [
                {
                    "SessionKey": "d0d8b5ab-9450-4beb-9f3e-9f7c1577d9bd",
                    "ConnectionState": 2
                }
            ]
        }
    ]
}
<!--NeedCopy-->

Active VDA machines associated information

LifecycleState eq 0 represents active machines.
MachineRole eq 0 represents a VDA machine.
Use $expand to get associated information.

Request

GET /monitorodata/Machines?$filter=LifecycleState eq 0 and Name ne null and DnsName ne '' and CatalogId ne null and MachineRole eq 0&$expand=CurrentLoadIndex,Catalog,Hypervisor HTTP/1.1
Host: api.cloud.com
Authorization: CWSAuth bearer=<Token>
Citrix-CustomerId: <CustomerId>
<!--NeedCopy-->

Response

HTTP/1.1 200 OK
Date: Thu, 01 Aug 2024 08:00:05 GMT
Content-Type: application/json; odata.metadata=minimal
Content-Length: 122546
Connection: keep-alive
odata-version: 4.0

{
    "@odata.context": "https://api.cloud.com/monitorodata/$metadata#Machines(CurrentLoadIndex(),Catalog(),Hypervisor())",
    "value": [
        {
            "Id": "17f8b8f5-0f27-4852-a399-00194801a283",
            "Sid": "S-1-5-21-1924580635-3864722089-3907235813-107439",
            "Name": "ENG\\ra-s19-cvad036",
            "DnsName": "ra-s19-cvad036.eng.citrite.net",
            "LifecycleState": 0,
            "IPAddress": null,
            "HostedMachineId": "ccf63697-723c-0845-17fe-ebe1e2e75d31",
            "HostingServerName": "ra-xen-07",
            "HostedMachineName": "ra-s19-cvad036",
            "IsAssigned": false,
            "IsInMaintenanceMode": false,
            "IsPendingUpdate": false,
            "AgentVersion": "2212.0.0.77",
            "AssociatedUserFullNames": "",
            "AssociatedUserNames": "",
            "AssociatedUserUPNs": "",
            "CurrentRegistrationState": 2,
            "RegistrationStateChangeDate": "2024-08-05T22:03:08.31Z",
            "LastDeregisteredCode": 0,
            "LastDeregisteredDate": "2024-08-05T22:02:33.64Z",
            "CurrentPowerState": 2,
            "CurrentSessionCount": 0,
            "ControllerDnsName": "A21828-46-2.prodcp5.local",
            "PoweredOnDate": "2024-08-05T10:01:50.4Z",
            "PowerStateChangeDate": "2024-08-05T22:03:08.31Z",
            "FunctionalLevel": 10,
            "FailureDate": null,
            "WindowsConnectionSetting": 0,
            "IsPreparing": false,
            "FaultState": 1,
            "OSType": "Windows 2019",
            "CurrentLoadIndexId": 17863392,
            "CatalogId": "11c5298e-4516-4c1b-b83a-efb219009b71",
            "DesktopGroupId": "ad9e2d3d-44ac-49b0-a34b-7affb5ce3596",
            "HypervisorId": "56ac3d9f-2691-4d2c-aacb-95726611fe79",
            "LastPowerActionType": 3,
            "LastPowerActionReason": 8,
            "LastPowerActionFailureReason": 400,
            "LastPowerActionCompletedDate": "2024-08-05T22:02:50.887Z",
            "Tags": [],
            "Hash": "",
            "MachineRole": 0,
            "CreatedDate": "2020-06-10T14:31:36.183Z",
            "ModifiedDate": "2024-08-05T22:47:00.103Z",
            "CurrentLoadIndex": {
                "Id": 17863392,
                "EffectiveLoadIndex": 0,
                "Cpu": 0,
                "Memory": 0,
                "Disk": 0,
                "Network": 0,
                "SessionCount": 0,
                "MachineId": "17f8b8f5-0f27-4852-a399-00194801a283",
                "CreatedDate": "2024-08-05T22:03:12.277Z",
                "ModifiedDate": "2024-08-06T06:51:36.9277153Z"
            },
            "Catalog": {
                "Id": "11c5298e-4516-4c1b-b83a-efb219009b71",
                "Name": "CVD\\BUR CVAD Development",
                "LifecycleState": 0,
                "ProvisioningType": 2,
                "PersistentUserChanges": 1,
                "IsMachinePhysical": false,
                "AllocationType": 2,
                "SessionSupport": 1,
                "ProvisioningSchemeId": null,
                "CreatedDate": "2020-05-19T00:02:03.903Z",
                "ModifiedDate": "2022-12-10T13:51:24.173Z"
            },
            "Hypervisor": {
                "Id": "56ac3d9f-2691-4d2c-aacb-95726611fe79",
                "Name": "BUR_Prod0",
                "Type": "XenServer",
                "LifecycleState": 0,
                "CreatedDate": "2020-05-15T12:32:30.587Z",
                "ModifiedDate": "2024-03-02T00:07:05.303Z"
            }
        }
    ]
}
<!--NeedCopy-->

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Resources

Citrix Monitor Service API OpenAPI Specification

Copy Download

How to retrieve data related to machine

September 12, 2024

Contributed by:

September 12, 2024

Contributed by:

How to retrieve data related to machine

Prerequisites

Active machines with count

Request

Response

Machines in failure state

Request

Response

MachineFailure details

Request

Response

Alive sessions on each machine

Active VDA machines associated information

Request

Response

Resources

Citrix Monitor Service API OpenAPI Specification

In this article

Resources

Citrix Monitor Service API OpenAPI Specification