Developer Documentation

Citrix Monitor Service API

How to retrieve data related to session

December 20, 2024

Contributed by:

Session represents a user connected to a desktop or an application.

Use Citrix Monitor Service API to get the data for entity session.

Prerequisites

Read the Get started with Citrix Cloud APIs section to ensure that you have the bearer token.
Use the endpoint https://{ApiGatewayEndpoint}/monitorodata/Sessions, for your region specific API gateway endpoint, see Supported API Gateway endpoints.
Invoke the API described in this document from a client host.

ApplicationInstances for active sessions

ConnectionState eq 5 represents the connection state of this session is active. For more information, see ConnectionState for a description of each connectionstate 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 session.
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 desktopgroup.
EndDate eq null represent the alive session.

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-->

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Resources

Citrix Monitor Service API OpenAPI Specification

Copy Download

How to retrieve data related to session

December 20, 2024

Contributed by:

December 20, 2024

Contributed by:

How to retrieve data related to session

Prerequisites

ApplicationInstances for active sessions

Request

Response

Connection and machine information of each session

Request

Response

SessionMetrics for alive sessions

Request

Response

Alive sessions for target DesktopGroup

Request

Response

Terminated sessions in a time range

Request

Response

Resources

Citrix Monitor Service API OpenAPI Specification

In this article

Resources

Citrix Monitor Service API OpenAPI Specification