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
-
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-->
-
Pick columns
sessionKey
,sessionScore
, andsessionState
to do the queryRequest 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.