Citrix Virtual Apps and Desktops REST APIs

How to use paging to query many objects through multiple API calls

Use REST APIs to query many objects that exceed the MaxRecordCount limit using paging.

Follow the prerequisites and examples to get started with this API.

You can make API requests using the PowerShell code, C# code, Python, or any tool that supports invoking the REST API.

Prerequisites to use paging to query many objects

Query many objects using any REST API tool

The following example describes how to query many machines which exceed the MaxRecordCount limit using paging. The maximum record count of the allowed is 1000 machines. For other types of site objects, apply this loop on a different request API.

If a query did not fully return the results due to a limit, the response includes a ContinuationToken string.

To obtain more results from the query, pass the ContinuationToken query parameter back into the same query to get the next batch of results. Repeat this step until the ContinuationToken value in response is null, indicating there’re no more unreturned results.

The continuationToken parameter is supported for all APIs that perform query or search on a large quantity of objects.

Request 1

GET https://[DdcServerAddress]/cvad/manage/Machines?limit=1000 HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
Authorization: CWSAuth bearer=<token-from-prerequisites>
Citrix-CustomerId: loy6oujtu6a4
Citrix-InstanceId: 22ded57c-0306-47e4-b6e8-fed6252759e1
<!--NeedCopy-->

Response 1

HTTP/1.1 200 OK
citrix-transactionid: f10859e0-63a9-4c2a-a51e-a126416246dc
content-Length: 7230586
content-Type: application/json; charset=utf-8
date: "Mon, 08 Nov 2021 14:48:51 GMT"
Server: Citrix Systems, Inc.

{
    "Items": [
        {
            "Id": "cf8582de-61dd-4c61-9649-636004c89907",
            "Uid": 1,
            ...
            "Name": "DEVPORTAL\\OrchVM-000001",
            ...
        },
        {
            "Id": "8bd7c72f-1a4c-4e00-ae4f-bf2eb34457f9",
            "Uid": 2,
            ...
            "Name": "DEVPORTAL\\OrchVM-000002",
            ...
        },
        ...
        {
            "Id": "f017d4ff-fdca-4e0d-bb55-9f72f000a3be",
            "Uid": 1000,
            ...
            "Name": "DEVPORTAL\\OrchVM-001000",
            ...
        }
    ],
    "ContinuationToken": "T7UhcehawR8PBTpc-tszgA=="
}
<!--NeedCopy-->

Request 2

GET https://[DdcServerAddress]/cvad/manage/Machines?limit=1000&continuationtoken=T7UhcehawR8PBTpc-tszgA%3d%3d HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
Authorization: CWSAuth bearer=<token-from-prerequisites>
Citrix-CustomerId: loy6oujtu6a4
Citrix-InstanceId: 22ded57c-0306-47e4-b6e8-fed6252759e1
<!--NeedCopy-->

Response 2

HTTP/1.1 200 OK
citrix-transactionid: f10859e0-63a9-4c2a-a51e-a126416246dc
content-Length: 7219243
content-Type: application/json; charset=utf-8
date: "Mon, 08 Nov 2021 14:49:13 GMT"
Server: Citrix Systems, Inc.

{
    "Items": [
        {
            "Id": "0bc13b4d-e82e-4e07-ae31-fe180ad91cb7",
            "Uid": 1001,
            ...
            "Name": "DEVPORTAL\\OrchVM-001001",
            ...
        },
        {
            "Id": "5e68b873-0fda-4045-80f4-fb79d7a320ab",
            "Uid": 1002,
            ...
            "Name": "DEVPORTAL\\OrchVM-001002",
            ...
        },
        ...
        {
            "Id": "cf314e6e-0ec6-47ba-aa77-88b63d4827bb",
            "Uid": 2000,
            ...
            "Name": "DEVPORTAL\\OrchVM-02000",
            ...
        }
    ],
    "ContinuationToken": "3EOYomxNlavb8GhMCzr7wg=="
}
<!--NeedCopy-->

Request 3

GET https://[DdcServerAddress]/cvad/manage/Machines?limit=1000&continuationtoken=3EOYomxNlavb8GhMCzr7wg%3d%3d HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
Authorization: CWSAuth bearer=<token-from-prerequisites>
Citrix-CustomerId: loy6oujtu6a4
Citrix-InstanceId: 22ded57c-0306-47e4-b6e8-fed6252759e1
<!--NeedCopy-->

Response 3

HTTP/1.1 200 OK
citrix-transactionid: f10859e0-63a9-4c2a-a51e-a126416246dc
content-Length: 2830950
content-Type: application/json; charset=utf-8
date: "Mon, 08 Nov 2021 14:53:57 GMT"
Server: Citrix Systems, Inc.

{
    "Items": [
        {
            "Id": "a829c80b-6b5b-461f-85f6-1f2c0aacf39f",
            "Uid": 2001,
            ...
            "Name": "DEVPORTAL\\OrchVM-002001",
            ...
        },
        {
            "Id": "d8d676be-34a2-4d39-9467-12b65599e730",
            "Uid": 2002,
            ...
            "Name": "DEVPORTAL\\OrchVM-002002",
            ...
        },
        ...
        {
            "Id": "af3fef40-d8a3-450c-a8ab-61f25a0ea520",
            "Uid": 2385,
            ...
            "Name": "DEVPORTAL\\OrchVM-02385",
            ...
        }
    ],
    "ContinuationToken": null
}
<!--NeedCopy-->

Query many objects using PowerShell

Learn from the following example to query many objects using any PowerShell code.

function GetMachinesInSiteWithPaging {
    param (
        [Parameter(Mandatory=$true)]
        [string] $customerid,
        [Parameter(Mandatory=$true)]
        [string] $siteid,
        [Parameter(Mandatory=$true)]
        [string] $bearerToken
    )
    $requestUri = "https://[DdcServerAddress]/cvad/manage/Machines?limit=1000"
    $headers = @{
        "Accept" = "application/json";
        "Authorization" = "CWSAuth Bearer=$bearerToken";
        "Citrix-CustomerId" = $customerid;
        "Citrix-InstanceId" = $siteid;
    }

    $response = Invoke-RestMethod -Uri $requestUri -Method GET -Headers $headers

    while ($response.ContinuationToken -ne $null)
    {
        $requestUriContinue = $requestUri + "&continuationtoken=" + $response.ContinuationToken
        $responsePage = Invoke-RestMethod -Uri $requestUriContinue -Method GET -Headers $headers
        $response.Items += $responsePage.Items
        $response.ContinuationToken = $responsePage.ContinuationToken
    }

    return $response
}

$customerid = "customer1"
$siteid = "61603f15-cdf9-4c7f-99ff-91636601a795"
$bearerToken = "ey1.."
$response = GetMachinesInSiteWithPaging $customerid $siteid $bearerToken
<!--NeedCopy-->

Query many objects using C#

Learn from the following example to query many objects using any C# code.

public static async Task<MachineResponseModelCollection> GetMachinesInSiteWithPaging(
    string customerid,
    string siteid,
    string bearerToken)
{
    var requestUri = "https://[DdcServerAddress]/cvad/manage/Machines?limit=1000";
    using (var client = new HttpClient())
    {
        client.DefaultRequestHeaders.Accept.ParseAdd("application/json");
        client.DefaultRequestHeaders.Add("Citrix-CustomerId", customerid);
        client.DefaultRequestHeaders.Add("Citrix-InstanceId", siteid);
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("CWSAuth Bearer=" + bearerToken);

        var response = await client.GetAsync(requestUri);

        if (response != null)
        {
            var content = await response.Content.ReadAsStringAsync();
            MachineResponseModelCollection machines = JsonConvert.DeserializeObject(content);
            var continuationToken = machines.ContinuationToken;
            
            while (machines.continuationToken != null)
            {
                var requestUriContinue = requestUri + "&continuationtoken=" + continuationToken;
                response = await client.GetAsync(requestUriContinue);
                content = await response.Content.ReadAsStringAsync();
                MachineResponseModelCollection machinePage = JsonConvert.DeserializeObject(content);
                machines.Items.Addrange(machinePage.Items);
                machines.continuationToken = machinePage.ContinuationToken;
            }
            
            return machines;
        }

        return null;
    }
}
<!--NeedCopy-->

Query many objects using Python

Learn from the following example to query many objects using any Python code.

import requests

def get_machines_in_site(bearerToken, customerid, siteid):
    request_uri = "https://[DdcServerAddress]/cvad/manage/Machines"
    headers = {
                'Authorization': 'CWSAuth Bearer=%s' % bearerToken,
                'Citrix-CustomerId': customerid,
                'Citrix-InstanceId': siteid,
                'Content-Type': 'application/json',
                'Accept': 'application/json'
              }

    response = requests.get(request_uri, headers = headers).json()
    while response.ContinuationToken is not None:
        request_uri_page = request_uri + "&continuationtoken=" + continuation_token
        response_page = requests.get(request_uri_page, headers = headers).json()
        response.Items += response_page.Items
        response.ContinuationToken = response_page.ContinuationToken

    return response.json()
<!--NeedCopy-->
Resources
Citrix Virtual Apps and Desktops REST APIs OpenAPI Specification
Copy Download
How to use paging to query many objects through multiple API calls