Session data request examples
The Session entity represents a user connected to a desktop or an application.
Use Citrix Monitor Service API to get the data for entity session.
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/Sessions
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.
ApplicationInstances for active sessions
-
ConnectionState eq 5
represents the sessions with active connection state. Please reference ConnectionState for a description of each connection state value. -
ModifiedDate
represents the target time range.
Request
GET /monitorodata/Sessions?$expand=ApplicationInstances&$filter=(ConnectionState eq 5) and (ModifiedDate gt 2024-08-06T07:00:00Z and ModifiedDate le 2024-08-06T07:10:00Z ) 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#Sessions(ApplicationInstances())",
"value": [
{
"SessionKey": "4569fdfd-54c4-44c8-81a9-40688a2771d6",
"StartDate": "2024-07-31T11:22:37.473Z",
"LogOnDuration": null,
"EndDate": null,
"ExitCode": 1,
"FailureId": null,
"FailureDate": null,
"ConnectionState": 5,
"SessionIdleTime": null,
"ConnectionStateChangeDate": "2024-08-06T07:08:50.72Z",
"LifecycleState": 0,
"CurrentConnectionId": 887132,
"UserId": 6,
"MachineId": "7eb414f9-533c-498f-a72f-b4459625100e",
"SessionType": 0,
"IsAnonymous": false,
"PublishedDesktopId": 93,
"CreatedDate": "2024-07-31T11:22:37.473Z",
"ModifiedDate": "2024-08-06T07:08:50.72Z",
"ApplicationInstances": []
}
]
}
<!--NeedCopy-->
Connection and machine information of each session
- Connection represents an initial connection or reconnect for a session.
- Use
$expand
operation to get the connection state for each session.
Request
GET /monitorodata/Sessions?$select=StartDate,LogOnDuration,EndDate&$expand=Machine($select=DesktopGroupId),Connections($select=LogOnStartDate,LogOnEndDate,BrokeringDuration,VMStartStartDate,VMStartEndDate,HdxStartDate,HdxEndDate,AuthenticationDuration,GpoStartDate,GpoEndDate,LogOnScriptsStartDate,LogOnScriptsEndDate,ProfileLoadStartDate,ProfileLoadEndDate,InteractiveStartDate,InteractiveEndDate;$filter=IsReconnect+eq+false)&$filter=LogOnDuration+ne+null+and+StartDate+gt+cast(2024-07-31T02:56:57.996Z,+Edm.DateTimeOffset)&$orderby=StartDate+desc 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#Sessions(StartDate,LogOnDuration,EndDate,Machine(DesktopGroupId),Connections(LogOnStartDate,LogOnEndDate,BrokeringDuration,VMStartStartDate,VMStartEndDate,HdxStartDate,HdxEndDate,AuthenticationDuration,GpoStartDate,GpoEndDate,LogOnScriptsStartDate,LogOnScriptsEndDate,ProfileLoadStartDate,ProfileLoadEndDate,InteractiveStartDate,InteractiveEndDate))",
"value": [
{
"StartDate": "2024-07-31T19:53:41.913Z",
"LogOnDuration": 147061,
"EndDate": null,
"Machine": {
"DesktopGroupId": "ad9e2d3d-44ac-49b0-a34b-7affb5ce3596"
},
"Connections": [
{
"LogOnStartDate": "2024-07-31T19:53:41.913Z",
"LogOnEndDate": "2024-07-31T19:55:59.583Z",
"BrokeringDuration": 34,
"VMStartStartDate": null,
"VMStartEndDate": null,
"HdxStartDate": null,
"HdxEndDate": null,
"AuthenticationDuration": 266,
"GpoStartDate": "2024-07-31T19:55:30.857Z",
"GpoEndDate": "2024-07-31T19:55:57.037Z",
"LogOnScriptsStartDate": null,
"LogOnScriptsEndDate": null,
"ProfileLoadStartDate": "2024-07-31T19:55:28.13Z",
"ProfileLoadEndDate": "2024-07-31T19:55:30.853Z",
"InteractiveStartDate": "2024-07-31T19:55:30.853Z",
"InteractiveEndDate": "2024-07-31T19:56:09.01Z"
}
]
}
]
}
<!--NeedCopy-->
SessionMetrics for alive sessions
-
EndDate is null
represents alive sessions. - Use
$expand=SessionMetrics
to get the metrics of each session.
Request
GET /monitorodata/Sessions?$filter=EndDate eq null &$select=StartDate,ConnectionState,SessionIdleTime&$expand=SessionMetrics($select=IcaRttMS),Machine($expand=DesktopGroup($select=Name)),Machine($select=Name),User($select=UserName),CurrentConnection($select=ClientName,ClientVersion,ClientAddress,ConnectedViaIPAddress,BrokeringDuration) 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#Sessions(StartDate,ConnectionState,SessionIdleTime,SessionMetrics(IcaRttMS),Machine(Name,DesktopGroup(Name)),User(UserName),CurrentConnection(ClientName,ClientVersion,ClientAddress,ConnectedViaIPAddress,BrokeringDuration))",
"value": [
{
"StartDate": "2024-06-25T07:46:56.673Z",
"ConnectionState": 2,
"SessionIdleTime": null,
"SessionMetrics": [
{
"IcaRttMS": 0
},
{
"IcaRttMS": 0
}
],
"Machine": {
"Name": "ENG\\ra-s19-cvad025",
"DesktopGroup": {
"Name": "CVD\\BUR CVAD Development"
}
},
"User": {
"UserName": "ameyag"
},
"CurrentConnection": {
"ClientName": "AMERENGAAD62201",
"ClientAddress": "10.122.198.42",
"ClientVersion": "24.5.0.131",
"ConnectedViaIPAddress": "3.3.11.7",
"BrokeringDuration": null
}
},
{
"StartDate": "2024-07-26T20:35:12.673Z",
"ConnectionState": 2,
"SessionIdleTime": "2024-07-26T20:48:00Z",
"SessionMetrics": [
{
"IcaRttMS": 0
},
{
"IcaRttMS": 0
}
],
"Machine": {
"Name": "ENG\\SHADOWS",
"DesktopGroup": {
"Name": "Remote PC - London"
}
},
"User": {
"UserName": "paulbro"
},
"CurrentConnection": {
"ClientName": "PAULMACHINE",
"ClientAddress": "192.168.68.88",
"ClientVersion": "24.5.0.131",
"ConnectedViaIPAddress": "10.3.72.60",
"BrokeringDuration": null
}
}
]
}
<!--NeedCopy-->
Alive sessions for target DesktopGroup
-
Machine/DesktopGroup/Id eq ad9e2d3d-44ac-49b0-a34b-7affb5ce3596
represents the target Desktop Group. -
EndDate eq null
represent alive sessions.
Request
GET /monitorodata/Sessions?$expand=Machine($expand=DesktopGroup)&$filter=(Machine/DesktopGroup/Id eq ad9e2d3d-44ac-49b0-a34b-7affb5ce3596) and (EndDate eq null) 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#Sessions(Machine(DesktopGroup()))",
"value": [
{
"SessionKey": "2d53d7f8-477c-4b18-a060-0081e050cc25",
"StartDate": "2024-06-25T07:46:56.673Z",
"LogOnDuration": 122030,
"EndDate": null,
"ExitCode": 1,
"FailureId": null,
"FailureDate": null,
"ConnectionState": 2,
"SessionIdleTime": null,
"ConnectionStateChangeDate": "2024-07-31T21:22:44.527Z",
"LifecycleState": 0,
"CurrentConnectionId": 886035,
"UserId": 4320,
"MachineId": "43a6ac00-9263-4c1b-acf5-f68267c6a26f",
"SessionType": 0,
"IsAnonymous": false,
"PublishedDesktopId": 3,
"CreatedDate": "2024-06-25T07:48:43.95Z",
"ModifiedDate": "2024-07-31T21:22:44.527Z",
"Machine": {
"Id": "43a6ac00-9263-4c1b-acf5-f68267c6a26f",
"Sid": "S-1-5-21-1924580635-3864722089-3907235813-171780",
"Name": "ENG\\ra-s19-cvad078",
"DnsName": "ra-s19-cvad078.eng.citrite.net",
"LifecycleState": 0,
"IPAddress": "10.60.8.178",
"HostedMachineId": "e59ef480-56b7-8f02-5233-efd5a161cc41",
"HostingServerName": "ra-xen-02",
"HostedMachineName": "ra-s19-cvad078",
"IsAssigned": false,
"IsInMaintenanceMode": false,
"IsPendingUpdate": false,
"AgentVersion": "2212.0.0.77",
"AssociatedUserFullNames": "Nataliia Taras",
"AssociatedUserNames": "CITRITE\\t_nataliiat",
"AssociatedUserUPNs": "Nataliia.Taras@citrix.com",
"CurrentRegistrationState": 1,
"RegistrationStateChangeDate": "2024-07-05T04:07:06.44Z",
"LastDeregisteredCode": 0,
"LastDeregisteredDate": "2024-06-24T05:33:40.443Z",
"CurrentPowerState": 3,
"CurrentSessionCount": 1,
"ControllerDnsName": "A21828-44-2.prodcp5.local",
"PoweredOnDate": "2024-06-24T10:06:16.1Z",
"PowerStateChangeDate": "2024-07-12T18:50:38.627Z",
"FunctionalLevel": 10,
"FailureDate": null,
"WindowsConnectionSetting": 0,
"IsPreparing": false,
"FaultState": 1,
"OSType": "Windows 2019",
"CurrentLoadIndexId": 17861538,
"CatalogId": "11c5298e-4516-4c1b-b83a-efb219009b71",
"DesktopGroupId": "ad9e2d3d-44ac-49b0-a34b-7affb5ce3596",
"HypervisorId": "56ac3d9f-2691-4d2c-aacb-95726611fe79",
"LastPowerActionType": 1,
"LastPowerActionReason": 8,
"LastPowerActionFailureReason": 400,
"LastPowerActionCompletedDate": "2024-06-24T10:06:21.937Z",
"Tags": [],
"Hash": "",
"MachineRole": 0,
"CreatedDate": "2021-04-27T12:41:12.097Z",
"ModifiedDate": "2024-07-12T18:50:38.627Z",
"DesktopGroup": {
"Id": "ad9e2d3d-44ac-49b0-a34b-7affb5ce3596",
"Name": "CVD\\BUR CVAD Development",
"IsRemotePC": false,
"DesktopKind": 1,
"LifecycleState": 0,
"SessionSupport": 1,
"DeliveryType": 2,
"IsInMaintenanceMode": false,
"MachineCost": 0.0,
"CurrencyType": null,
"AutoscaleTagId": 0,
"CreatedDate": "2020-05-19T00:07:37.387Z",
"ModifiedDate": "2024-06-04T00:05:01.13Z"
}
}
}
]
}
<!--NeedCopy-->
Terminated sessions in a time range
-
ConnectionState ne 3
represents terminated sessions. -
FailureDate gt 2020-12-04T15:08:25.000Z
gets failures after the mentioned timestamp.
Request
GET /monitorodata/Sessions?$filter=ConnectionState ne 3 or FailureDate gt 2020-12-04T15:08:25.000Z 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#Sessions",
"value": [
{
"SessionKey": "3f570c39-a0d0-4dda-9e2e-001040b22ea7",
"StartDate": "2024-05-17T09:22:06.87Z",
"LogOnDuration": null,
"EndDate": "2024-05-17T09:22:06.87Z",
"ExitCode": 101,
"FailureId": 13,
"FailureDate": "2024-05-17T09:22:06.87Z",
"ConnectionState": 3,
"SessionIdleTime": null,
"ConnectionStateChangeDate": "2024-05-17T09:22:06.87Z",
"LifecycleState": 3,
"CurrentConnectionId": 857484,
"UserId": 2762,
"MachineId": "510ff5f6-887c-4a43-a042-c6bf03313da0",
"SessionType": 0,
"IsAnonymous": false,
"PublishedDesktopId": null,
"CreatedDate": "2024-05-17T09:22:06.87Z",
"ModifiedDate": "2024-05-17T09:22:06.87Z"
}
]
}
<!--NeedCopy-->
Running Desktop sessions
-
ConnectionState eq 5
andEndDate eq null
represents running sessions. -
SessionType eq 0
represents desktop sessions
Request
GET /monitorodata/Sessions?$filter=ConnectionState eq 5 and EndDate eq null and SessionType eq 0&$select=SessionKey,StartDate,SessionType&$expand=PublishedDesktopName,User($select=Fullname,Upn),Machine($select=Name)&$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#Sessions",
"value": [
{
"SessionKey":"1b8b2cbf-8281-49a5-9822-00026b2ef1f8",
"StartDate":"2024-11-26T08:18:36.743Z",
"SessionType":0,
"PublishedDesktopName":{
"Id":5,
"PublishedName":"Desktop-W10-TS-P"
},
"User":{
"Upn":"user.name@citrix.com",
"FullName":"User Name"
},
"Machine":{
"Name":"LAB\\TEST-MVDA-01"
}
}
]
}
<!--NeedCopy-->
Number of active sessions by Desktop Group and Session Type
As part of this example, we query the Sessions entity, but expand to the DesktopGroup via the Machine entity. We group by the DesktopGroup name and the Session type. The list of Session Types can be found here: SessionType.
Request
GET /monitorodata/Sessions?$apply=filter(StartDate ge 2025-05-02 and EndDate eq null)/expand(Machine,expand(DesktopGroup,filter(Name ne null)))/groupby((Machine/DesktopGroup/Name,SessionType),aggregate(SessionKey with countdistinct as SessionCount)) 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#Sessions",
"value": [
{
"@odata.id":null,
"SessionType":0,
"SessionCount":36,
"Machine":{
"@odata.id":null,
"DesktopGroup":{
"@odata.id":null,
"Name":"LAB3-W10-P"
}
}
}
]
}
<!--NeedCopy-->
Session data request examples
In this article
Copied!
Failed!