Citrix Analytics ODATA API

Overview

CAS ODATA v4 REST API helps you to easily fetch the aggregated data. Currently, we are supporting user to fetch session data from CAS performance data source.

This article provides a guidance about how to use the APIs.

API specifications

Authentication

The implementation uses Citrix Cloud bearer token to authenticate.

References:

Citrix Cloud client ID and Citrix Cloud client secret

The following is sample request to get the token.

Request sample:

    POST https://api.cloud.com/cctrustoauth2/{customerid}/tokens/clients
    Accept: application/json
    Content-Type: application/x-www-form-urlencoded
    Body: grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}
<!--NeedCopy-->

Response sample:

HTTP/1.1 200 OK
Content-Type: application/json
...
{
"token_type": "bearer",
"access_token": "ey1..",
"expires_in": "3600"
}
<!--NeedCopy-->

Note:

The expiration period of the bearer token is 1 hour. Regenerate it if you need to do the query after one hour.

Endpoints

Global: https://api.cloud.com/casodata

Sample:

https://api.cloud.com/casodata/sessions?year=2023&month=04&day=14 will fetch the aggregated sessions data for date 2023/04/14 (UTC).

Service path

This section includes information on service path and entity names such as sessions, machines, and users. For example, see the following sample service path:

/sessions?year=2023&month=04&day=14
<!--NeedCopy-->

The parameters year, month, and day are mandatory and added in UTC format.

The data of a specified hour is also supported, the path is as follows:

/sessions?year=2023&month=04&day=14&hour=10 (Fetch the data of 2023/04/14 10:00)
<!--NeedCopy-->

HTTP headers

Key Sample Value Mandatory
Authorization CwsAuth bearer=   Yes
Citrix-CustomerId Yes
Content-Type application/json   Yes
Citrix-TransactionId     No
Accept-Encoding gzip No

System operators

CAS ODATA API supports the following basic odata system options:

System option Sample
$select https:///casodata/sessions?year=2023&month=04&day=14&$select=sessionKey,sessionScore,sessionState
$orderby https:///casodata/sessions?year=2023&month=04&day=14&$select=sessionKey,sessionScore,sessionState&$orderby=sessionScore desc
$top https:///casodata/sessions?year=2023&month=04&day=14&$select=sessionKey,sessionScore,sessionState&$top=1
$top&$skip https:///casodata/sessions?year=2023&month=04&day=14&$select=sessionKey,sessionScore,sessionState&$top=10&$skip=20
$count https:///casodata/sessions?year=2023&month=04&day=14&$count=true
$filters https:///casodata/sessions?year=2023&month=04&day=14&$select=sessionKey,sessionScore,sessionState&$filter=sessionScore ne 20

Note:

Don’t add any space in the value of $select option.

$filter operators and functions

CAS ODATA API supports the following odata logical operators and string functions for $filter option:

Category Operators Samples
Logical operators



eq/ne/gt/lt/le/ge https:///casodata/sessions?year=2023&month=04&day=14&$select=sessionKey,sessionScore,sessionState&$filter=sessionScore ge 20
not https:///casodata/sessions?year=2023&month=04&day=14&$select=sessionKey,sessionScore,sessionState,deliveryGroupName&$filter=not(deliveryGroupName eq null)
and/or https:///casodata/sessions?year=2023&month=04&day=14&$select=sessionKey,sessionScore,sessionState,logonDuration&$filter=sessionState eq ‘5’ and (sessionScore le 20 or logonDuration gt 19.914)
in https:///casodata/sessions?year=2023&month=04&day=14&$select=sessionKey,sessionScore,sessionState,logonDuration&$filter=sessionState in (‘5’,’3’)
not in https:///casodata/sessions?year=2023&month=04&day=14&$select=sessionKey,sessionScore,sessionState,logonDuration&$filter=not (sessionState in (‘5’,’3’))
String functions

contains https:///casodata/sessions?year=2023&month=04&day=14&$select=sessionKey,sessionScore,sessionState,deliveryGroupName&$filter=contains(deliveryGroupName,’PRD’)
startswith https:///casodata/sessions?year=2023&month=04&day=14&$select=sessionKey,sessionScore,sessionState,deliveryGroupName&$filter=not endswith(deliveryGroupName,’CVAD Development’)
endswith https:///casodata/sessions?year=2023&month=04&day=14&$select=sessionKey,sessionScore,sessionState,deliveryGroupName&$filter=startswith(sessionKey,’09c3268e’)

Entities and data attributes

The following three CAS performance entities are supported:

Sample use cases

Get the metadata and pick some columns from them to do the query

  1. Requesting the metadata

    Request sample:

    curl --location 'https://api.cloud.com/casodata/$metadata' \
    --header 'Authorization: CwsAuth bearer=eyJhbGciOiJSUzI1NiIsInR5.....' \
    --header 'Citrix-CustomerId: qt64gkrzji7h' \
    --header 'Content-Type: application/json'
    <!--NeedCopy-->
    

    Response sample:

    <?xml version="1.0" encoding="UTF-8"?>
    <edmx:Edmx Version="4.0" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
    <edmx:DataServices>
    <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="cas.odata.v1">
    <EntityType Name="session">
    <Property Name="timestamp" Type="Edm.String"></Property>
    <Property Name="sessionKey" Type="Edm.String"></Property>
    <Property Name="sessionScore" Type="Edm.Double"></Property>
    <Property Name="sessionState" Type="Edm.String"></Property>
    ...
    <Property Name="sessionLaunchStatus" Type="Edm.Int32"></Property>
    <Property Name="sessionLaunchStatusCustom" Type="Edm.String"></Property>
    </EntityType>
    <EntityContainer Name="Container">
    <EntitySet Name="sessions" EntityType="cas.odata.v1.session" IncludeInServiceDocument="false"></EntitySet>
    </EntityContainer>
    </Schema>
    </edmx:DataServices>
    </edmx:Edmx>
    <!--NeedCopy-->
    
  2. Pick columns sessionKey, sessionScore, and sessionState to do the query

    Request sample:

    curl --location 'https://api.cloud.com/casodata/sessions?year=2023&month=04&day=14&%24select=sessionKey%2CsessionScore%
    2CsessionState' \
    --header 'Authorization: CwsAuth bearer=eyJhbGciOiJSUzI1NiIsInR5.....' \
    --header 'Citrix-CustomerId: qt64gkrzji7h' \
    --header 'Content-Type: application/json'
    <!--NeedCopy-->
    

    Response sample:

    {
    "@odata.context": "$metadata#sessions(sessionKey,sessionScore,sessionState)/$entity",
    "value": [
    {
    "sessionKey": "009e7f0f-5707-4083-934f-24d8ad5e91f8",
    "sessionScore": -1.0,
    "sessionState": "2"
    },
    ...
    {
    "sessionKey": "ff0504e3-0867-414a-b0b2-beb73f06fdad",
    "sessionScore": 0.0,
    "sessionState": "5"
    }
    ]
    }
    <!--NeedCopy-->
    

Fetch all the data of a specified day with pagination

The default limitation of the query is 1000 rows.

User is able to set the value of $top option to limit the result rows in the query. In this scenario, the next page link is provided at the bottom of query response.

Request sample:

curl --location 'https://api.cloud.com/casodata/sessions?year=2023&month=04&day=14&%24top=100' \
--header 'Authorization: CwsAuth bearer=eyJhbGciOiJSUzI1NiIsInR5.....' \
--header 'Citrix-CustomerId: qt64gkrzji7h' \
--header 'Content-Type: application/json'
<!--NeedCopy-->

Response sample:

{
"@odata.context": "$metadata#sessions/$entity",
"value": [
{
"timestamp": "2023-03-28T00:00:00.000Z",
"sessionKey": "009e7f0f-5707-4083-934f-24d8ad5e91f8",
"sessionScore": 79.0,
"sessionState": "2",
"sessionType": "0",
"userName": "81d0260b529c11fbb05c8dfabb3d312182e6af9deecfc6c036768df2ed3c3a39",
"sessionStartTime": "2023-03-28T17:38:38.000Z",
"machineName": "253f6a031c9b65cbb7bcc3f137b9878fe0effef010757aec54420776a0d2dd71",
"deliveryGroupName": "CVD\\BUR CVAD Development",
"logonDuration": 18.69,
"brokeringDuration": 0.0,
"vmStartDuration": 0.0,
"hdxConnectionDuration": 0.0,
"authenticationDuration": 0.0,
"gpoDuration": 0.0,
"logonScriptsDuration": 0.0,
"profileLoadDuration": 0.0,
"interactiveSessionsDuration": 0.0,
"siteName": "cloudxdsite",
"icaRtt": 125.38,
"reconnects": 0.0,
"wanLatency": 0,
"hostDelay": 0,
"dcLatency": 0,
"endpointLocationCity": null,
"endpointReceiverVersion": "21.6.0.47",
"endpointOS": "Windows",
"endpointLocationCountry": null,
"endpointLinkSpeed": -1.0,
"endpointName": "64368231b5d925e40d67449640ca110e9658f63eef37d2579b09b975cc7f7e88",
"endpointIP": "850a4b2abc159a2f7d44dac564bda06afad0c558a070a2681f5cc0e1aa81991c",
"vdaIP": null,
"gatewayFQDN": null,
"connectionType": "External",
"connectorName": null,
"connectorGatewayLatency": 0.0,
"networkInterfaceType": null,
"isp": null,
"sessionLaunchType": "ICA",
"throughputBytesReceived": -1.0,
"throughputBytesSent": -1.0,
"inputBandwidthConsumed": -1.0,
"outputBandwidthAvailable": -1.0,
"outputBandwidthUsed": -1.0,
"networkLatency": -1.0,
"outputBandwidthUtilization": -1.0,
"siteId": "090e20c8-c852-4a92-9b3f-dfb8d8b2ab61",
"sessionLaunchStatus": 0,
"sessionLaunchStatusCustom": "Succeeded"
},
...
{
"timestamp": "2023-04-14T00:00:00.000Z",
"sessionKey": "ff0504e3-0867-414a-b0b2-beb73f06fdad",
"sessionScore": 0.0,
"sessionState": "5",
"sessionType": "0",
"userName": "aed8a56c38d5d2824d8699a48cdd1b19eb3b16f135c8d61bf2cd6acd465aa998",
"sessionStartTime": "2023-03-09T21:39:51.000Z",
"machineName": "5603b4dcad97424b6329caccc9cc6ad949b764bbc0015bc6e2a2b4938e4be954",
"deliveryGroupName": "Remote PC - Miami LABs",
"logonDuration": 0.0,
"brokeringDuration": 0.0,
"vmStartDuration": 0.0,
"hdxConnectionDuration": 0.0,
"authenticationDuration": 0.0,
"gpoDuration": 0.0,
"logonScriptsDuration": 0.0,
"profileLoadDuration": 0.0,
"interactiveSessionsDuration": 0.0,
"siteName": "cloudxdsite",
"icaRtt": 0.0,
"reconnects": 0.0,
"wanLatency": 0,
"hostDelay": 0,
"dcLatency": 0,
"endpointLocationCity": null,
"endpointReceiverVersion": null,
"endpointOS": "Windows 10",
"endpointLocationCountry": null,
"endpointLinkSpeed": -1.0,
"endpointName": "Precision 5550",
"endpointIP": "e74dbbbd20d20f971c0254c6680aad800ad3932c4740544b39a42bb422424272",
"vdaIP": null,
"gatewayFQDN": null,
"connectionType": "External",
"connectorName": null,
"connectorGatewayLatency": 0.0,
"networkInterfaceType": null,
"isp": null,
"sessionLaunchType": "ICA",
"throughputBytesReceived": -1.0,
"throughputBytesSent": -1.0,
"inputBandwidthConsumed": -1.0,
"outputBandwidthAvailable": -1.0,
"outputBandwidthUsed": -1.0,
"networkLatency": -1.0,
"outputBandwidthUtilization": -1.0,
"siteId": "090e20c8-c852-4a92-9b3f-dfb8d8b2ab61",
"sessionLaunchStatus": 0,
"sessionLaunchStatusCustom": "Succeeded"
}
],
"@odata.nextLink": "https://api.cloud.com/casodata/sessions?year=2023&month=04&day=14&%
24skip=100&%24top=100"
}
<!--NeedCopy-->

Get all the data of a certain session (filter the data with sessionkey)

Request sample:

curl --location 'https://api.cloud.com/casodata/sessions?year=2023&month=04&day=14&%24filter=sessionKey%20eq%20%
27009e7f0f-5707-4083-934f-24d8ad5e91f8%27' \
--header 'Authorization: CwsAuth bearer=eyJhbGciOiJSUzI1NiIsInR5.....' \
--header 'Citrix-CustomerId: qt64gkrzji7h' \
--header 'Content-Type: application/json'
<!--NeedCopy-->

Response sample:

{
"@odata.context": "$metadata#sessions/$entity",
"value": [
{
"timestamp": "2023-04-14T00:00:00.000Z",
"sessionKey": "009e7f0f-5707-4083-934f-24d8ad5e91f8",
"sessionScore": -1.0,
"sessionState": "2",
"sessionType": "0",
"userName": "81d0260b529c11fbb05c8dfabb3d312182e6af9deecfc6c036768df2ed3c3a39",
"sessionStartTime": "2023-04-05T17:32:45.000Z",
"machineName": "253f6a031c9b65cbb7bcc3f137b9878fe0effef010757aec54420776a0d2dd71",
"deliveryGroupName": "CVD\\BUR CVAD Development",
"logonDuration": 21.2,
"brokeringDuration": 0.0,
"vmStartDuration": 0.0,
"hdxConnectionDuration": 0.0,
"authenticationDuration": 0.0,
"gpoDuration": 0.0,
"logonScriptsDuration": 0.0,
"profileLoadDuration": 0.0,
"interactiveSessionsDuration": 0.0,
"siteName": "cloudxdsite",
"icaRtt": 0.0,
"reconnects": 0.0,
"wanLatency": 0,
"hostDelay": 0,
"dcLatency": 0,
"endpointLocationCity": null,
"endpointReceiverVersion": "21.6.0.47",
"endpointOS": "Windows",
"endpointLocationCountry": null,
"endpointLinkSpeed": -1.0,
"endpointName": "64368231b5d925e40d67449640ca110e9658f63eef37d2579b09b975cc7f7e88",
"endpointIP": "8dbacd9197f4d3dc068fd44b4837828f8e10a19358b14e96d439cfc82042b70f",
"vdaIP": null,
"gatewayFQDN": null,
"connectionType": "External",
"connectorName": null,
"connectorGatewayLatency": 0.0,
"networkInterfaceType": null,
"isp": null,
"sessionLaunchType": "ICA",
"throughputBytesReceived": -1.0,
"throughputBytesSent": -1.0,
"inputBandwidthConsumed": -1.0,
"outputBandwidthAvailable": -1.0,
"outputBandwidthUsed": -1.0,
"networkLatency": -1.0,
"outputBandwidthUtilization": -1.0,
"siteId": "090e20c8-c852-4a92-9b3f-dfb8d8b2ab61",
"sessionLaunchStatus": 0,
"sessionLaunchStatusCustom": "Succeeded"
}
]
}
<!--NeedCopy-->

Count all the active sessions of a certain day

Request sample:

curl --location 'https://api.cloud.com/casodata/sessions?year=2023&month=04&day=14&%24count=true&%24filter=sessionState%
20eq%20%275%27' \
--header 'Authorization: CwsAuth bearer=eyJhbGciOiJSUzI1NiIsInR5.....' \
--header 'Citrix-CustomerId: qt64gkrzji7h' \
--header 'Content-Type: application/json'
<!--NeedCopy-->

Response sample:

207

Data source

The CAS self service search dashboard visulize and display the data to the customer admins and enable search functionality. The ODATA API uses the same data source and provide more flexibilities to customer admins to fetch and filter the data. For more information, see Tabular data.

Citrix Analytics ODATA API