Machine data request examples
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 after2024-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
andLastPowerActionFailureReason
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-->
In this article
- Prerequisites
- Active machines with count
- Machines in a failure state
- Get Machine failure details
- Find failed machine power actions
- Alive sessions on each machine
- Active VDA machines associated information
- Get VDA machine availability over time
- List of Hotfixes applied to each machine
- Get a list of all the VDA versions