Citrix Monitor Service API

Machine resource utilization request examples

June 2, 2025

Contributed by:

Use Citrix Monitor Service API to get machine level CPU and memory usage.

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/ResourceUtilizationSummary 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.

Powered on machine CPU and memory usage at hourly level

Granularity = 60 represents hourly level metrics.
UptimeInMinutes > 0 represents the machine powered on in this hour.

Request

GET /monitorodata/ResourceUtilizationSummary?$filter=Granularity eq 60 and SummaryDate eq 2024-07-30T08:00:00Z and UptimeInMinutes gt 0&$expand=Machine($select=Name,AgentVersion),DesktopGroup($select=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 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#ResourceUtilizationSummary",
    "value": [
        {
            "MachineId": "31a02fb0-b673-4520-b94d-017fa2acd3b8",
            "Granularity": 60,
            "SummaryDate": "2025-05-05T08:00:00Z",
            "DesktopGroupId": "ad9e2d3d-44ac-49b0-a34b-7affb5ce3596",
            "AvgPercentCpu": 0.99298245335618651,
            "PeakPercentCpu": 3.5789473056793213,
            "AvgUsedMemory": 7918633224.9824562,
            "PeakUsedMemory": 7937829187.3684206,
            "AvgTotalMemory": 17170366464.0,
            "TotalSessionCount": 1,
            "AvgIcaRttInMs": null,
            "AvgLogOnDurationInMs": null,
            "UptimeInMinutes": 60,
            "UpTimeWithoutSessionInMinutes": 0,
            "DisconnectTimeInMinutes": 60,
            "CreatedDate": "2024-07-30T09:13:46.247Z",
            "ModifiedDate": "2024-07-30T09:13:46.247Z",
            "Machine": {
                "Name": "EWS\\MI-PMD005",
                "AgentVersion": "2407.0.100.274"
            },
            "DesktopGroup": {
                "Name": "MI-PMD"
            }
        }
    ]
}
<!--NeedCopy-->

Powered on machine CPU and memory usage at day level

Granularity = 1440 represents day level metrics.
UptimeInMinutes > 0 represents the machine powered on in this day.

Request

GET /monitorodata/ResourceUtilizationSummary?$filter=Granularity eq 1440 and SummaryDate eq 2024-07-30T00:00:00Z and UptimeInMinutes gt 0 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#ResourceUtilizationSummary",
    "value": [
        {
            "MachineId": "17f8b8f5-0f27-4852-a399-00194801a283",
            "Granularity": 1440,
            "SummaryDate": "2025-05-05T00:00:00Z",
            "DesktopGroupId": "ad9e2d3d-44ac-49b0-a34b-7affb5ce3596",
            "AvgPercentCpu": 1.1274837264250215,
            "PeakPercentCpu": 14.733333587646484,
            "AvgUsedMemory": 4474693852.6077623,
            "PeakUsedMemory": 4756543078.4,
            "AvgTotalMemory": 17170366464.0,
            "TotalSessionCount": 0,
            "AvgIcaRttInMs": null,
            "AvgLogOnDurationInMs": null,
            "UptimeInMinutes": 724,
            "UpTimeWithoutSessionInMinutes": null,
            "DisconnectTimeInMinutes": null,
            "IdleTimeInMinutes": null,
            "CreatedDate": "2024-07-31T00:13:46.027Z",
            "ModifiedDate": "2024-07-31T00:13:46.027Z",
            "Machine": {
                "Name": "EWS\\MI-PMD005",
                "AgentVersion": "2407.0.100.274"
            },
            "DesktopGroup": {
                "Name": "MI-PMD"
            }
        }
    ]
}
<!--NeedCopy-->

Machine resource utilization aggregates by delivery group

The query is more complex, as we first need to compute percentage values based on the used and total memory metrics. We group by the DesktopGroup name and the hourly timestamp and calculate average and max values.

$apply operation includes a filter stage, a compute stage, an expand stage and a groupby/aggregate stage. See the OData documentation for usage details.

Request

GET /monitorodata/ResourceUtilizationSummary?$apply=filter(Granularity eq 60 and SummaryDate ge 2025-05-03 and UptimeInMinutes gt 0 and AvgTotalMemory gt 0 and AvgUsedMemory gt 0 and PeakUsedMemory gt 0)/compute(100 mul AvgUsedMemory div AvgTotalMemory as AvgPercentMemory, 100 mul PeakUsedMemory div AvgTotalMemory as PeakPercentMemory)/expand(DesktopGroup,filter(Name ne null))/groupby((DesktopGroup/Name,SummaryDate),aggregate(AvgPercentCpu with average as AvgPercentCpu, PeakPercentCpu with max as PeakPercentCpu, AvgPercentMemory with average as AvgPercentMemory, PeakPercentMemory with max as PeakPercentMemory)) 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#ResourceUtilizationSummary",
    "value": [
        {
            "@odata.id": null,
            "SummaryDate": "2025-05-03T00:00:00Z",
            "PeakPercentMemory": 14.249562365700822,
            "AvgPercentMemory": 14.176066487959879,
            "PeakPercentCpu": 1.7819637060165405,
            "AvgPercentCpu": 0.64738541841506958,
            "DesktopGroup": {
                "@odata.id": null,
                "Name": "MI-PMD"
            }
        },
        {
            "@odata.id": null,
            "SummaryDate": "2025-05-03T01:00:00Z",
            "PeakPercentMemory": 14.241976541431665,
            "AvgPercentMemory": 14.18313095499029,
            "PeakPercentCpu": 2.2718720436096191,
            "AvgPercentCpu": 0.65315361817677819,
            "DesktopGroup": {
                "@odata.id": null,
                "Name": "MI-PMD"
            }
        }
    ]
}
<!--NeedCopy-->

Daily average uptime by delivery group

The query gets the daily resource utilization summaries and averages the UptimeInMinutes by Desktop Group over the defined time period.

$apply operation includes a filter stage, an expand stage and a groupby/aggregate stage. See the OData documentation for usage details.

Request

GET /monitorodata/ResourceUtilizationSummary?$apply=filter(Granularity eq 1440 and SummaryDate ge 2025-05-01 and SummaryDate le 2025-05-10)/expand(Machine,expand(DesktopGroup,filter(Name ne null)))/groupby((DesktopGroupId, DesktopGroup/Name), aggregate(cast(UptimeInMinutes, Edm.Int32) with average as AvgUptimeInMinutes)) 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#ResourceUtilizationSummary",
    "value": [
        {
            "@odata.id": null,
            "DesktopGroupId": "97123b25-ad22-4a37-a6bd-0355952fdfe1",
            "AvgUptimeInMinutes": 1222.7,
            "DesktopGroup": {
                "@odata.id": null,
                "Name": "LRO-P"
            }
        },
        {
            "@odata.id": null,
            "DesktopGroupId": "e3123b36-6807-490c-b71e-2af99bbfb0d8",
            "AvgUptimeInMinutes": 1437.75,
            "DesktopGroup": {
                "@odata.id": null,
                "Name": "MacVDA"
            }
        },
        {
            "@odata.id": null,
            "DesktopGroupId": "4e123ac2-99d8-49a9-a082-3949284b0e8d",
            "AvgUptimeInMinutes": 993.9785714285714,
            "DesktopGroup": {
                "@odata.id": null,
                "Name": "W10-TS-P"
            }
        }
    ]
}
<!--NeedCopy-->

Unused machines over time period

In this example, we calculate the total number of sessions running on each of the machines over the selected time period and then filter for the machines with no sessions. Note that we have to cast the TotalSessionCount to a larger integer type (is Int16) for the aggregation to succeed.

Request

GET /monitorodata/ResourceUtilizationSummary?$apply=filter(Granularity eq 60 and SummaryDate ge 2025-05-05 and UptimeInMinutes gt 0)/expand(Machine,expand(DesktopGroup,filter(Name ne null)))/compute(cast(TotalSessionCount,Edm.Int64) as TotalSessionCountInt64 )/groupby((DesktopGroup/Name,MachineId,Machine/Name),aggregate(TotalSessionCountInt64 with sum as TotalSessionCountSum))/filter(TotalSessionCountSum 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#ResourceUtilizationSummary",
    "value": [
        {
            "@odata.id":null,
            "MachineId":"5bf5d243-2395-46d1-bd7e-83f77ae65db3",
            "TotalSessionCountSum":0,
            "Machine": {
                "@odata.id": null,
                "Name": "LAB\\TEST-MVDA-01"
            },
            "DesktopGroup":{
                "@odata.id":null,
                "Name":"DG-W10-PMD"
            }
        },
        {
            "@odata.id":null,
            "MachineId":"a9dbe063-16f6-45c2-bb1b-a6f978fe9810",
            "TotalSessionCountSum":0,
            "Machine": {
                "@odata.id": null,
                "Name": "LAB\\TEST-MVDA-02"
            },
            "DesktopGroup":{
                "@odata.id":null,
                "Name":"DG-W10-LRO-2-P"
            }
        }
    ]
}
<!--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

Machine resource utilization request examples

June 2, 2025

Contributed by:

June 2, 2025

Contributed by:

Machine resource utilization request examples

Prerequisites

Powered on machine CPU and memory usage at hourly level

Request

Response

Powered on machine CPU and memory usage at day level

Request

Response

Machine resource utilization aggregates by delivery group

Request

Response

Daily average uptime by delivery group

Request

Response

Unused machines over time period

Request

Response

Resources

Citrix Monitor Service API OpenAPI Specification

In this article

Resources

Citrix Monitor Service API OpenAPI Specification