Skip to content

Access Monitor Service data using the OData v4 endpoint in Citrix Cloud

You can now query the Monitor Service data using the OData Version 4 endpoint based on ASP .Net Web API. Customers can now run aggregation queries on the Monitor Service data; this feature was not available in OData Version 3 or earlier.


Accessing Monitor Service data using the OData v4 endpoint in Citrix Cloud is currently under preview.

A Citrix Cloud customer can access the data with the V4 endpoint after authentication using the Citrix Cloud username and authentication token or the bearer token.


To ensure optimal performance and resource utilization of the Delivery Controller, one OData query is permitted per customer at a time. Query time out is 30 seconds. If you exceed the limit of one request at a time, a 429 Too Many Requests response status code is returned.

Supported API Gateway endpoints

  • US region:
  • EU region:
  • AP-S region:


  • The "https://{Customer_Id}" URL is replaced with "https://{ApiGatewayEndpoint}". The HTTP header "Customer" is now replaced with "Citrix-CustomerId".
  • For Government and Japan ( customers, the existing URLs and header name (Customer) remain unchanged.

HTTP error codes

See HTTP error codes to know about the various error codes and their descriptions.

Generate Citrix Cloud Bearer Token

You can obtain the bearer token using either of the following methods:

Method 1: XenApp and XenDesktop Remote PowerShell SDK

  1. Download the Remote PowerShell SDK from here.
  2. Install the SDK on any computer in your resource location.
  3. Open a PowerShell command prompt. (administrator rights are not required)
  4. Add the Citrix snap-ins: asnp citrix*.
  5. Execute the cmdlet, Get-XdAuthentication, it prompts you for Citrix Cloud authentication.
  6. On successful authentication, the bearer token is stored in the current PowerShell session.
  7. Execute the cmdlet, Get-Variable to list all the variables in the current PowerShell session.
  8. The list contains a variable, GLOBAL:XDAuthToken containing bearer token as value.
  9. Copy the bearer token value to be used in the OData query.

Method 2: Citrix Cloud API:

You may obtain the bearer token using the Citrix Cloud APIs. For more information on the steps, see

For the details of the Monitor Service schema, see Monitor Service Schema.

To determine the values returned by the Monitor Service OData API, see Citrix.Monitor.Model.

The list of URLs for available data sets is available at URLs for Available Data Sets. Replace http://{dc-host}/Citrix/Monitor/OData/v4/Data with "https://{ApiGatewayEndpoint}".

Use cases and walk-through of OData APIs ands PowerShell SDK

Here's a video explaining the various use cases of OData APIs and PowerShell SDK used in Citrix Virtual Apps and Desktops.

OData APIs and PowerShell SDK use cases walk-through video

Access methods

Access using MS Excel PowerQuery

1. Open Excel (Excel 2016 has PowerQuery inbuilt. If you are using earlier versions of Excel, install PowerQuery, see

2. In Excel 2016, go to Data menu > Get & Transform group > New Query > From Other Sources > click Blank Query

Blank Query

3. In the Query Editor window, go to Home menu > Query group > click Advanced Editor.

Query editor window

4. In the Advanced Editor window, type the following query:

    Source = OData.Feed
                            Headers =
                                        #”Authorization = "<YourToken>",
                                        #"Citrix-CustomerId" = "<YourCustomerId"

Advanced editor

Replace <YourCustomerId> and <YourToken> with the values of CustomerID and bearer token you obtained as described in the Generate the Citrix Cloud Bearer Token section. Make sure that the <YourToken> is in the format, “CWSAuth bearer= ”. Once the No Syntax errors have been detected is displayed in the bottom of the window, click Done.

5. In case of first login, a Please specify how to connect message is displayed. Click Edit Credentials, the Access an OData feed window appears. Make sure that the Anonymous tab and the base URL are selected and click Connect.

6. Upon successful authentication, the results are displayed as a table. In this example, the table lists all the Machines of the CustomerId. If the authentication fails, either the bearer token or the CustomerId might be invalid. Please verify the same and try again.

Access using C# Client Library

Use a Simple.OData.Client to create a C# client for an OData v4 endpoint. For information about installation of its Nuget Package, see

Install the package using the Nuget Package Manager:

Install-Package Simple.OData.Client

After installation, use the package with the following command:

using Simple.OData.Client;

As the OData query in the Cloud requires the Citrix Cloud authentication, the OData clients must pass the bearer token (as documented in the Generate Citrix Cloud Bearer Token section) and the CustomerId. Set up the headers as follows, before creating the OData query:

ODataClientSettings settings = new ODataClientSettings();
settings.BeforeRequest += request =>
    request.Headers.Add("Authorization", "<BearerToken>");
    request.Headers.Add("Citrix-CustomerId", "<customerId>");

settings.BaseUri = new Uri("https://{ApiGatewayEndpoint}");
client = new ODataClient(settings);

Data can be retrieved by using async methods. This example lists all the Machines

public static async void GetMachines()
    var machines = await client.FindEntriesAsync("Machines");
    foreach(var machine in machines)

Access using PowerShell

Below is a sample OData query triggered from PowerShell with the headers initialized and the Raw XML output redirected to a file:

PS C:\> $headers = @{"Authorization" = "<BearerToken>”; "Citrix-CustomerId" = "<Your Customer Id>"}

PS C:\> $url = https://{ApiGatewayEndpoint}/Users

PS C:\> $result = Invoke-WebRequest -Uri $url -Headers $headers

PS C:\> $result.Content > <Path-to-Output-File>

Access using other REST clients (Ex. Postman Chrome Ext.)

  1. Install Postman from Chrome extensions. See
  2. Launch the application.
  3. Select GET in the dropdown and type in the URL to request. Postman
  4. Insert headers with your token and customerId. Click Send.
  5. If authentication is successful, response data is seen in the Response section of Postman.

Aggregation Queries in Odata v4

Aggregation queries were not supported in OData Version 3 and earlier. It is supported in OData Version 4. As per OData documentation, aggregation can be done using the $apply=aggregate() field. Below are few examples that show data aggregation. Use them after https://{ApiGatewayEndpoint}/

?$apply=aggregate([column to aggregate] with [aggregation type] as [column to aggregate])

Aggregation Types:

  • Count : Machines?$count=true

This gives the total number of machines.

  • Sum : Sessions?$apply=aggregate(SessionType with sum as SessionType)

This gives the sum of session types in Sessions.

  • Min : Machines?$apply=aggregate(LifecycleState with min as LifecycleState)

This gives the minimum of all the life cycle states.

OData Pagination

Citrix Monitor supports OData pagination. All OData v4 endpoints return a maximum of 100 records per page with a link to the next 100 records. The following PowerShell script fetches applications in batches of 100 records using Citrix Cloud authentication following the @odata.nextLink property in the response.

$customerId = "[customerid]"
$api = "https://{ApiGatewayEndpoint}"
$endpoint = "$api/Applications"

$bearer = "CWSAuth bearer=[token]"
$headers = @{'Citrix-CustomerId'=$customerId;'Authorization'=$bearer}

$results = Invoke-RestMethod $endpoint -Headers $headers -Verbose
Write-Host Number of items returned in the first call : , $results.value.Count

while($results.'@odata.nextLink' -ne $null)
    $results = Invoke-RestMethod $results.'@odata.nextLink' -Headers $headers -Verbose
    Write-Host "Number of items returned in next call : ", $results.value.Count
Was this article helpful?