About Citrix Monitor Service API

Use the Citrix Monitor Service REST APIs to collect, analyze, and categorize data from the Citrix Virtual Apps and Desktops and Citrix DaaS (formerly Citrix Virtual Apps and Desktops service) site.

The Citrix Monitor Service API is built on the SQL Server Monitor database that is populated during processing and consolidation. This API is based on the ASP.NET Web API Framework. The Citrix Monitor Service API uses the Open Data (OData) protocol, which is a Web protocol for querying and updating data, built upon Web technologies such as HTTP. ASP.NET Web API Framework supports OData Version 4.

You can access Citrix Monitor Service API using an OData consumer API. OData consumers are applications that consume data exposed using the OData protocol. For more access methods, please read Data Access Methods.

If you are a Citrix Virtual Apps and Desktop administrator with read-only privileges, you can use the API to get following types of data from the Citrix Virtual Apps and Desktops and Citrix DaaS site:

• Data relating to connection failures, session usage, logon duration, and load balancing

• Machines in a failure state, hotfixes applied to a machine, hosted application usage, and application failure

• Machine level CPU, memory, and disk usage

• Process level CPU and memory usage

The preceding data received using the Citrix Monitor Service REST APIs allows you to:

• Analyze historical trends for future planning

• Perform detailed troubleshooting of connection and machine failures

• Extract information for feeding into other tools and processes; for example, using Microsoft Excel’s PowerPivot tables to display the data in different ways

• Build a custom user interface based on the data provided by the API

• Run aggregation queries with the OData Version 4 endpoints to get basic grouping and aggregation functionality.

To get additional information on performing the preceding the tasks, go through the details on how to access the monitor service data, data access privilege, Data Access protocol.

Use the various access methods to export the data using OData API. Follow the Citrix Monitor Service REST APIs reference to get information on the methods, parameters, field descriptions, error types, and error values associated with the APIs.

Have a question on Citrix Monitor Service API? Find answers and ask questions, on the Citrix Developer Exchange forum.

Supported API Gateway endpoints

Use one of the following endpoints based on the geographical region you selected while accessing the Citrix Monitor Service data:

• US/EU/AP-S region:https://api.cloud.com/monitorodata
• Japan region: https://api.citrixcloud.jp/monitorodata

Who can use this API service

To use the Monitor Service OData API, you must be a XenApp and XenDesktop administrator. To call the API, you require read-only privileges; however, the data returned is determined by XenApp and XenDesktop administrator roles and permissions.

For example, Delivery Group Administrators can call the Monitor Service API but the data they can obtain is controlled by Delivery Group access set up using Citrix Studio.

For more information about XenApp and XenDesktop administrator roles and permissions, see Delegated Administration.

Data Available using the API

Currently, the following API entities are supported:

• ApplicationActivitySummaries: The activity summary of each application.

• Applications: Represents a virtualized application running on a session.

• ApplicationInstances: Record of an instance of a running application.

• Sessions: Represents a user connected to a desktop.

• ConnectionFailureLogs: Log of each connection failure in the Site.

• Connections: Represents an initial connection or reconnect for a session.

• ConnectionFailureCategories: Grouping for connection failure types.

• Machines: Machines in the Site.

• Catalogs: Catalog images in the Site.

• LoadIndexes: Load Index data received from the Virtual Delivery Agent (VDA).

• LogOnMetrics: Timestamps related to Interactive Session breakdown.

• DesktopGroups: Delivery Groups in the Site.

• ResourceUtilization: Represents a resource utilization statistics of a particular machine every 5 minutes.

• ResourceUtilizationSummary: Represents a hourly level and day level resource utilization statistics of a particular machine.

• Hypervisors: Hosts (hypervisors) in the Site.

• MachineFailureLogs: Log of each machine failure by start and end date in the Site.

• MachineHotfixLogs: HotfixHistory relates the machine and hotfixes installed/ removed.

• Hotfixes: Hotfixes applied to a machine.

• MachineMetric: Represents a machine metrics statistics of a particular machine.

• MachineMetricSummary: Represents a machine metrics statistics summary of a particular machine.

• Processes: Represents a process utilization statistics of a particular process on a machine.

• ProcessDataLimitedMachines: List the process data limited machines.

• ProcessUtilization: Represents a process utilization statistics of a particular process on a machine.

• ProcessUtilizationDaySummary: Day level summary for ProcessUtilization.

• ProcessUtilizationHourSummary: Hour level summary for ProcessUtilization.

• ProcessUtilizationMinuteSummary: Minute level summary for ProcessUtilization.

• SessionMetrics: Represents a session metrics of a particular session for a machine.

• Users: Users that have launched a session in the Site.

• DesktopOSDesktopSummaries: Summry of Desktop usage.

• FailureLogSummaries: Failures (connection/machine) counts by time period and Delivery Group.

• LoadIndexSummaries: Load Index averages by time period and machine.

• LogOnSummaries: Logon breakdown rollup/summary per hour/day.

• NotificationActionEmails: NotificationActionEmails.

• NotificationRuleActions: NotificationRuleActions.

• NotificationRules: NotificationRules.

• NotificationRuleGroups: NotificationRuleGroups.

• NotificationRuleParameters: NotificationRuleParameters.

• NotificationRuleParameterChangeLogs: NotificationRuleParameterChangeLogs.

• NotificationRuleTargets: NotificationRuleTargets.

• NotificationRuleTargetValues: NotificationRuleTargetValues.

• NotificationEmailAddresses: NotificationEmailAddresses.

• NotificationEmailServerConfigurations: NotificationEmailServerConfigurations.

• Notifications: Notifications.

• NotificationsLogs: NotificationsLogs.

• NotificationTargets: NotificationTargets.

• NotificationSnmpConfigurations: NotificationSnmpConfigurations.

• ServerOSDesktopSummaries: ServerOSDesktopSummaries.

• SessionActivitySummaries: Session counts and logon data by time period and delivery group.

• TaskLogs: Log of all tasks and their status that have been run as part of the internal Monitor Service.

• ApplicationErrors: Records of application errors.

• ApplicationFaults: Records of application fault.

• ProbeEndpoints: Machines running Citrix Probe Agent to probe applications in the Site.

• ProbeRules: Application probes configured in the Site.

• ProbeLogs: Results of probes run per application.

• ProbeResults: Results of probes run (with failure stage) per application.

• ProbeStages: Probe Stage.

• ProbeRuleEndpoints: Probe Rule Target.

• ProbeRuleApplications: Probe Rule Application.

• MachineSummaries: Summary of machine metrics.

• SessionAutoReconnects: Records of session auto reconnect.

• ProbeLogDesktop: Probe Log Desktop.

• ProbeRuleDesktop: Probe Rule Desktop.

• ProbeResultDesktop: Probe Result Desktop.

• ProbeDesktop: Probe Desktop.

• SessionRecordingServers: Session Recording Servers.

• PublishedDesktopNames: Published Desktop Names.

• LhcReport: LhcReport.

• MachineCostSavingsSummaries: Summary of machine cost saving metrics.

• CloudConnectorServiceStatus: Cloud connector service status.

• DirectorAgent: Director agent.

• MachineCosts: Model entity of the cost of a VM.

• ComponentResourceUtilizations: Resource Utilization for a given component at a given time.

Authentication

All Monitor Service REST APIs require authentication which is specified in the following parameters:

• Citrix CustomerID: CustomerId is passed in the Citrix-CustomerId header
• CCAuth Token: Secure HTTP requests sent to Citrix Cloud (CC) use a custom Authorization header that contains a CC bearer token. Bearer tokens are required for actions that take place on behalf of a user.

For information on how to obtain the Citrix-CustomerId and generate a custom Authorization header that contains the bearer token, see the Get started with Citrix Cloud APIs section.

Required headers

Please set the following headers for the API call

• Citrix-CustomerId: Your customer Id.
• Authorization: In format CWSAuth bearer=<Token>, <Token> is obtained from the Authentication process.
• Accept-Encoding: Set this header to gzip, deflate, br to reduce the network traffic. Some tools, such as Postman, will set this value automatically.
• User-Agent: Set this header to <existing script/tool version> can help Citrix fine tune the api performance and better rate limiting for customers who are leveraging OData for either internal automation and workflows or third party tools for data extraction, and monitoring.

Here is a sample request:

GET /monitorodata/$metadata HTTP/1.1
Host: api.cloud.com
Authorization: CWSAuth bearer=<Token>
Citrix-CustomerId: <CustomerId>
Accept-Encoding: gzip, deflate, br
User-Agent: third-party-tool-v1
<!--NeedCopy-->

Concurrent request limitation

For maintaining the service quality and preventing abuse, the service enforces a request concurrency limitation. If multiple concurrent requests are issued, new requests may fail with the “429 Too Many Requests” status code.

In such a scenario, fine-tune the script, increase the number of retries, extend the interval between queries, or simplify the query.