Developer Documentation
Citrix Monitor Service API
Current Release 7.15 LTSR
View PDF

Machine data request examples

June 2, 2025
Contributed by: 
C

The Machines entity represents physical or virtual machines in the customer’s cloud or on-prem Site. Use Citrix Monitor Service API to get machine data.

NOTE: The request examples of this section target cloud setups. However the OData queries also apply to on-premises setups. Simply adjust the request URL to be of the form http[s]://{MonitorServiceHost}/Citrix/Monitor/OData/v4/Data/{ODataQuery} and change the authentication to NTLM.

Prerequisites

  • Read the Get started with Citrix Cloud APIs section to ensure that you have a valid bearer token.
  • Use the endpoint https://{ApiGatewayEndpoint}/monitorodata/Machines for your requests. See Supported API Gateway endpoints for a list of region specific 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 appends the record count in the 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 a failure state

  • FailureDate is null represents machines not in a failure state.
  • FailureDate ne null represents machines in a failure state.
  • FailureDate ge 2024-07-30T00:00:00Z helps filter 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-->

Get Machine failure details

  • The MachineFailures entity provides details about Machine failures. Use the $expand operation to enrich the response records with these details.

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",
    "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-->

Find failed machine power actions

  • The LastPowerActionReason and LastPowerActionFailureReason fields can be used to filter for the failed machine power actions. Check page Descriptions for enums and error codes for details.

Request 

GET /monitorodata/Machines?$filter=LifecycleState eq 0 and DesktopGroup/SessionSupport eq 1 and (cast(LastPowerActionReason,'Edm.Int32') eq 6 or cast(LastPowerActionReason,'Edm.Int32') eq 7 or cast(LastPowerActionReason,'Edm.Int32') eq 8) and (cast(LastPowerActionFailureReason,'Edm.Int32') eq 300 or cast(LastPowerActionFailureReason,'Edm.Int32') eq 402 or cast(LastPowerActionFailureReason,'Edm.Int32') eq 401) and MachineRole eq 0&$orderby=Name&$skip=0&$top=50&$expand=DesktopGroup($select=Name)&$select=Sid,Id,Name,IsAssigned,IPAddress,FaultState,LastDeregisteredCode,FailureDate,CurrentPowerState,CurrentSessionCount,IsInMaintenanceMode,LastPowerActionFailureReason,LastPowerActionCompletedDate 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": "a9db1234-16f6-45c2-bb1b-a6f978fe9810",
            "Sid": "S-1-5-21-2061182105-2775619996-3779015820-12345",
            "Name": "EWS\\LRO003",
            "IPAddress": null,
            "IsAssigned": true,
            "IsInMaintenanceMode": false,
            "LastDeregisteredCode": 2,
            "CurrentPowerState": 2,
            "CurrentSessionCount": 0,
            "FailureDate": null,
            "FaultState": 1,
            "LastPowerActionFailureReason": 401,
            "LastPowerActionCompletedDate": "2025-05-13T04:59:50.18Z",
            "DesktopGroup": {
                "Name": "LRO-2-P"
            }
        }
    ]
}
<!--NeedCopy-->

Alive sessions on each machine

  • Sessions in the $expand operation enriches the response records with the sessions running on a machine.
  • EndDate eq null represents the sessions that are 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",
    "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 like catalog, hypervisor and load.

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",
    "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-->

Get VDA machine availability over time

  • MachineSummaries entity provides aggregate machine metrics at hourly or daily granularity.
  • The $expand operations enriches the records with Desktop Group information.

Request 

GET /monitorodata/MachineSummaries?$filter=Granularity eq 60 and SummaryDate ge 2025-05-01&$select=SummaryDate,PoweredOnMachinesCount,RegisteredMachinesCount,MachinesInMaintenanceModeCount,MachinesCount&$expand=DesktopGroup($select=Id,Name)&$orderby=DesktopGroup/Name 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: 2546
Connection: keep-alive
odata-version: 4.0

{
    "@odata.context": "https://api.cloud.com/monitorodata/$metadata#Machines",
    "value": [
        {
            "SummaryDate":"2025-05-01T00:00:00Z",
            "PoweredOnMachinesCount":7,
            "RegisteredMachinesCount":5,
            "MachinesInMaintenanceModeCount":0,
            "MachinesCount":8,
            "DesktopGroup":{
                "Id":"002683cd-b3a5-4fc8-913c-9f0d12e4d7cb",
                "Name":"LAB3-W10-P"
            }
        },
        {
            "SummaryDate":"2025-05-01T01:00:00Z",
            "PoweredOnMachinesCount":0,
            "RegisteredMachinesCount":0,
            "MachinesInMaintenanceModeCount":1,
            "MachinesCount":2,
            "DesktopGroup":{
                "Id":"002683cd-b3a5-4fc8-913c-9f0d12e4d7cb",
                "Name":"LAB3-W10-P"
            }
        }
    ]
}
<!--NeedCopy-->

List of Hotfixes applied to each machine

As part of this example, we query the MachineHotfixLogs entity, which includes records with each of the hotfixes applied to the VDA machines. We enrich the result records with Machine and DesktopGroup information.

  • MachineHotfixLogs provides a list of the hotfixes.
  • Use $expand to get associated Machine, DesktopGroup and Hotfix information.

Request 

GET /monitorodata/MachineHotfixLogs?$filter=CreatedDate ge 2025-02-01&$expand=Machine($select=Name;$expand=DesktopGroup($select=Name)),Hotfix&$orderby=Machine/DesktopGroup/Name,Machine/Name 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: 2546
Connection: keep-alive
odata-version: 4.0

{
    "@odata.context": "https://api.cloud.com/monitorodata/$metadata#Machines(CurrentLoadIndex(),Catalog(),Hypervisor())",
    "value": [
        {
            "Id":10073,
            "MachineId":"6829529e-4126-417c-90a7-a372dc7bcbc7",
            "HotfixId":"33fd700d-d35f-4b6c-81e0-30cd793547f7",
            "ChangeType":1,
            "CurrentState":true,
            "CreatedDate":"2024-11-27T13:24:38.05Z",
            "ModifiedDate":"2024-11-27T13:24:38.05Z",
            "Machine":{
                "Name":"LAB\\TEST-MVDA-01",
                "DesktopGroup":{
                "Name":"DG-W10-PMD"
                }
            },
            "Hotfix":{
                "Id":"33fd700d-d35f-4b6c-81e0-30cd793547f7",
                "Name":"IdentityAssertionWX64_7_33_5000",
                "Article":"http://support.citrix.com/article/CTX579943",
                "ArticleName":"CTX579943",
                "FileName":"Citrix.Authentication.IdentityAssertion_x64",
                "FileFormat":"MSI",
                "Version":"10.9.5000.8",
                "ComponentName":"Citrix Identity Assertion VDA Plugin",
                "ComponentVersion":"10.9.5000.8",
                "CreatedDate":"2024-06-07T19:42:49.38Z",
                "ModifiedDate":"2024-06-07T19:42:49.38Z"
            }
        }
    ]
}
<!--NeedCopy-->

Get a list of all the VDA versions

Query the Machines entity, aggregate over the distinct versions and calculate the number of machines running each of the VDA versions per delivery group.

Request 

GET /monitorodata/Machines?$apply=filter(AgentVersion ne null and DesktopGroup/Name ne null)/expand(DesktopGroup,filter(Name ne null))/groupby((DesktopGroup/Name,AgentVersion),aggregate(Id with countdistinct as MachineCount)) 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: 2546
Connection: keep-alive
odata-version: 4.0

{
    "@odata.context": "https://api.cloud.com/monitorodata/$metadata#Machines(CurrentLoadIndex(),Catalog(),Hypervisor())",
    "value": [
        {
            "@odata.id":null,
            "AgentVersion":"2407.0.10.101",
            "MachineCount":46,
            "DesktopGroup":{
                "@odata.id":null,
                "Name":"DG-W10-LRO-P"
            }
        },
        {
            "@odata.id":null,
            "AgentVersion":"2402.0.100.609",
            "MachineCount":11,
            "DesktopGroup":{
                "@odata.id":null,
                "Name":"DG-W10-PMD"
            }
        }
    ]
}
<!--NeedCopy-->
Resources
Citrix Monitor Service API OpenAPI Specification
Copy Download
Machine data request examples
June 2, 2025
Contributed by: 
C
June 2, 2025
Contributed by: 
C

In this article

Resources
Citrix Monitor Service API OpenAPI Specification
Copy Download
Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.