OpenAPI Specification
openapi: 3.2.0
info:
title: VDI & DAAS Session API
version: 1.0.0
description: Session statistics report
servers:
- url: https://api.controlup.com/historical
security:
- bearer-jwt:
- read
- write
tags:
- name: Session
description: Session statistics report
paths:
/v1/sessions:
get:
tags:
- Session
summary: Get session statistics
description: Returns statistics for all user sessions. Visit the <a href='https://support.controlup.com/docs/user-sessions-activity-report' target='_blank'>Session Activity Report</a> documentation for column descriptions and more details.
operationId: getSessionsStatistics
parameters:
- name: presetType
in: query
description: Set the type of statistics to return for each user session.
required: true
schema:
type: string
enum:
- activity
- client
- cvad
- horizon
- resources
- ux
- list
- name: userAccount
in: query
description: Filter sessions by user account, provided in the Domain\username format.
required: false
schema:
type: string
- name: userName
in: query
description: Filter sessions by user display name (partial match, e.g. 'John Doe'). If both userName and userAccount are provided, userAccount takes precedence.
required: false
schema:
type: string
example: John Doe
- name: serverName
in: query
description: Filter sessions by server name. This parameter is only applicable when the preset is set to LIST.
required: false
schema:
type: string
- name: _timeFrom
in: query
description: 'Start date and time of the search period in the format: YYYY-MM-DD''T''hh:mm:ss.sssZ'
required: true
schema:
type: string
format: date-time
example: '2025-02-01T00:00:00.000Z'
- name: _timeTo
in: query
description: 'End date and time of the search period in the format: YYYY-MM-DD''T''hh:mm:ss.sssZ'
required: true
schema:
type: string
format: date-time
example: '2025-02-02T00:00:00.000Z'
- name: logonDurationgt
in: query
description: Minimum logon duration in seconds
required: false
schema:
type: integer
format: int32
- name: logonDurationlt
in: query
description: Maximum logon duration in seconds
required: false
schema:
type: integer
format: int32
- name: _page
in: query
description: The page number returned. The first page is 1.
schema:
type: integer
format: int32
minimum: 1
example: 1
- name: _limit
in: query
description: The number of items returned per page. Minimum is 1.
schema:
type: integer
format: int32
maximum: 100000
minimum: 1
example: 20
responses:
'200':
description: Successfully retrieved
content:
application/json:
schema:
type: string
oneOf:
- $ref: '#/components/schemas/SessionActivityResponse'
- $ref: '#/components/schemas/SessionCvadResponse'
- $ref: '#/components/schemas/SessionHorizonResponse'
- $ref: '#/components/schemas/SessionResourcesResponse'
- $ref: '#/components/schemas/SessionUxResponse'
- $ref: '#/components/schemas/SessionClientResponse'
- $ref: '#/components/schemas/SessionListResponse'
application/xml:
schema:
type: string
oneOf:
- $ref: '#/components/schemas/SessionActivityResponse'
- $ref: '#/components/schemas/SessionCvadResponse'
- $ref: '#/components/schemas/SessionHorizonResponse'
- $ref: '#/components/schemas/SessionResourcesResponse'
- $ref: '#/components/schemas/SessionUxResponse'
- $ref: '#/components/schemas/SessionClientResponse'
- $ref: '#/components/schemas/SessionListResponse'
'400':
description: Bad Request - one of the inputs isn't correct
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
'401':
description: User is not authorized to access the resource
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
'403':
description: Authorization details are not provided
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
'501':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
'504':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
/v1/sessions/timeline/{sessionUid}:
get:
tags:
- Session
summary: Get session timeline
description: Returns the timeline of session state changes for a specific session.
operationId: getSessionTimeline
parameters:
- name: sessionUid
in: path
description: Session UID to get timeline for
required: true
schema:
type: integer
format: int64
responses:
'200':
description: Successfully retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/SessionTimelineResponse'
application/xml:
schema:
$ref: '#/components/schemas/SessionTimelineResponse'
'400':
description: Bad Request - one of the inputs isn't correct
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
'401':
description: User is not authorized to access the resource
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
'403':
description: Authorization details are not provided
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
'501':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
'504':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
/v1/sessions/details:
get:
tags:
- Session
summary: Get individual session details
description: Returns activity details of individual session. Visit the <a href='https://support.controlup.com/docs/user-sessions-activity-report' target='_blank'>Session Activity Report</a> documentation for column descriptions and more details.
operationId: getSessionDetails
parameters:
- name: machineName
in: query
description: The name of virtual machine.
required: true
schema:
type: string
- name: computerId
in: query
description: The name of virtual machine.
required: true
schema:
type: string
- name: sessionUid
in: query
description: Session uid used to identify a session. This value is returned in the session statistics.
required: true
schema:
type: integer
format: int64
- name: isNormalLogoff
in: query
description: Was logoff explicit.
required: true
schema:
type: boolean
- name: sessionStartDateTime
in: query
description: Start datetime of requested session details.
required: true
schema:
type: string
- name: sessionEndDateTime
in: query
description: End datetime of requested session details.
required: false
schema:
type: string
- name: _page
in: query
description: The page number returned. The first page is 1.
schema:
type: integer
format: int32
minimum: 1
example: 1
- name: _limit
in: query
description: The number of items returned per page. Minimum is 1.
schema:
type: integer
format: int32
maximum: 100000
minimum: 1
example: 20
responses:
'200':
description: Successfully retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/SessionDetailsEventsResponse'
application/xml:
schema:
$ref: '#/components/schemas/SessionDetailsEventsResponse'
'400':
description: Bad Request - one of the inputs isn't correct
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
'401':
description: User is not authorized to access the resource
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
'403':
description: Authorization details are not provided
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
'501':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
'504':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
/v1/sessions/aggregated:
get:
tags:
- Session
summary: Get aggregated session activity
description: Returns aggregated session activity metrics (avg/min/max/count) grouped by a single session dimension such as folder, delivery group, site, user, protocol, or initial program. Visit the <a href='https://support.controlup.com/docs/user-sessions-activity-report' target='_blank'>Session Activity Report</a> documentation for column descriptions and more details.
operationId: getSessionsAggregated
parameters:
- name: groupBy
in: query
description: Single session dimension to group rows by.
required: true
schema:
type: string
enum:
- folderPath
- folderId
- deliveryGroup
- deliveryGroupId
- eucSiteName
- eucSiteId
- cvadSiteName
- horizonSite
- userAccount
- userFullName
- protocol
- initialProgram
- name: metrics
in: query
description: One or more session metrics to aggregate. Repeat the parameter for multiple values.
required: true
schema:
type: array
items:
type: string
enum:
- duration_in_seconds
- logon_duration
- profile_load_time
- desktop_load_time
- group_policy_load_time
- logon_duration_other
- cvad_logon_duration
- cvad_profile_load_time
- cvad_group_policy_load_time
- session_protocol_latency_avg
- session_protocol_latency_max
- session_protocol_latency_min
- rtt_avg
- rtt_max
- rtt_min
- active_time_in_seconds
- idle_time_in_seconds
- disconnected_time_in_seconds
- name: aggregations
in: query
description: 'Aggregation functions to apply to each metric. Repeat for multiple. Default: avg.'
required: false
schema:
type: array
items:
type: string
enum:
- avg
- min
- max
- count
- name: _sortBy
in: query
description: 'Response field to sort by (must equal a returned <metric>_<aggregation>, session_count, or the groupBy field). Default: <first metric>_<first aggregation>.'
required: false
schema:
type: string
- name: _sortOrder
in: query
description: 'Sort order. Default: desc.'
required: false
schema:
type: string
enum:
- asc
- desc
- name: _timeFrom
in: query
description: 'Start date and time of the search period in the format: YYYY-MM-DD''T''hh:mm:ss.sssZ'
required: true
schema:
type: string
format: date-time
example: '2025-02-01T00:00:00.000Z'
- name: _timeTo
in: query
description: 'End date and time of the search period in the format: YYYY-MM-DD''T''hh:mm:ss.sssZ'
required: true
schema:
type: string
format: date-time
example: '2025-02-02T00:00:00.000Z'
- name: userAccount
in: query
description: Filter sessions by user account, provided in the Domain\username format.
required: false
schema:
type: string
- name: serverName
in: query
description: Filter sessions by server name.
required: false
schema:
type: string
- name: logonDurationgt
in: query
description: Minimum logon duration in seconds (pre-aggregation filter).
required: false
schema:
type: integer
format: int32
- name: logonDurationlt
in: query
description: Maximum logon duration in seconds (pre-aggregation filter).
required: false
schema:
type: integer
format: int32
- name: _page
in: query
description: The page number returned. The first page is 1.
schema:
type: integer
format: int32
minimum: 1
example: 1
- name: _limit
in: query
description: The number of items returned per page. Minimum is 1.
schema:
type: integer
format: int32
maximum: 100000
minimum: 1
example: 20
responses:
'200':
description: Successfully retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/SessionAggregatedResponse'
application/xml:
schema:
$ref: '#/components/schemas/SessionAggregatedResponse'
'400':
description: Bad Request - one of the inputs isn't correct
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
'401':
description: User is not authorized to access the resource
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
'403':
description: Authorization details are not provided
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
'501':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
'504':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
application/xml:
schema:
$ref: '#/components/schemas/HistoricalErrorResponse'
components:
schemas:
SessionHorizonResult:
type: object
properties:
user_name:
type: string
logoff_time:
type: string
user_full_name:
type: string
session_id:
type: string
login_time:
type: string
duration_in_seconds:
type: integer
format: int64
logon_duration:
type: integer
format: int64
initial_program:
type: string
initial_client_branch_name:
type: string
profile_load_time:
type: integer
format: int64
cpu_usage_avg:
type: integer
format: int64
gpu_cpu_utilization_avg:
type: integer
format: int64
memory_usage_avg:
type: integer
format: int64
desktop_load_time:
type: integer
format: int64
group_policy_load_time:
type: integer
format: int64
io_usage_iops_avg:
type: integer
format: int64
disk_read_kbyte_per_sec_avg:
type: integer
format: int64
disk_write_kbyte_per_sec_avg:
type: integer
format: int64
logoff_flag:
type: string
machine_name:
type: string
domain_name:
type: string
hz_pod:
type: string
hz_session_start_time:
type: string
hz_farm_name:
type: string
hz_pool_display_name:
type: string
hz_session_pool_name:
type: string
hz_pool_name:
type: string
initial_hz_agent_version:
type: string
initial_hz_client_version:
type: string
initial_hz_client_connection_server_url:
type: string
initial_hz_security_gateway_name:
type: string
hz_site:
type: string
initial_hz_client_type:
type: string
hz_session_type:
type: string
session_uid:
type: string
user_account:
type: string
computer_id:
type: string
SessionAggregatedResponse:
type: object
properties:
metadata:
$ref: '#/components/schemas/UserMetadata'
data:
type: array
items:
$ref: '#/components/schemas/SessionAggregatedResult'
ActiveUrl:
type: object
properties:
active_url:
type: string
start_time:
type: string
end_time:
type: string
SessionUxResult:
type: object
properties:
user_name:
type: string
logoff_time:
type: string
user_full_name:
type: string
session_id:
type: string
login_time:
type: string
logon_duration:
type: integer
format: int64
session_protocol_latency_avg:
type: integer
format: int64
initial_program:
type: string
user_ad_ou:
type: string
initial_client_branch_name:
type: string
rtt_avg:
type: integer
format: int64
session_protocol_latency_max:
type: integer
format: int64
memory_usage_avg:
type: integer
format: int64
desktop_load_time:
type: integer
format: int64
group_policy_load_time:
type: integer
format: int64
io_usage_iops_avg:
type: integer
format: int64
disk_read_kbyte_per_sec_avg:
type: integer
format: int64
disk_write_kbyte_per_sec_avg:
type: integer
format: int64
logon_duration_other:
type: integer
format: int64
active_time_percentage:
type: integer
format: int64
idle_time_percentage:
type: integer
format: int64
disconnect_time_percentage:
type: integer
format: int64
logoff_flag:
type: string
machine_name:
type: string
frames_per_second_avg:
type: integer
format: int64
session_uid:
type: string
user_account:
type: string
computer_id:
type: string
cvad_session_key:
type: string
SessionDetailsResult:
type: object
properties:
session_events:
type: array
items:
$ref: '#/components/schemas/SessionState'
session_client_info:
type: array
items:
$ref: '#/components/schemas/SessionClientInfo'
active_apps:
type: array
items:
$ref: '#/components/schemas/ActiveApp'
active_urls:
type: array
items:
$ref: '#/components/schemas/ActiveUrl'
SessionClientResult:
type: object
properties:
username:
type: string
logoff_time:
type: string
user_full_name:
type: string
session_id:
type: string
login_time:
type: string
logon_duration:
type: integer
format: int64
initial_client_ip:
type: string
initial_client_branch_name:
type: string
logon_duration_other:
type: integer
format: int64
active_time_percentage:
type: integer
format: int64
idle_time_percentage:
type: integer
format: int64
disconnect_time_percentage:
type: integer
format: int64
logoff_flag:
type: string
machine_name:
type: string
domain_name:
type: string
client_wifi_signal_avg:
type: integer
format: int64
total_session_latency_avg:
type: integer
format: int64
internet_latency_avg:
type: integer
format: int64
lan_latency_avg:
type: integer
format: int64
initial_client_name:
type: string
initial_protocol_type:
type: string
initial_client_nic_speed:
type: integer
format: int64
initial_client_os_name:
type: string
initial_client_os_version:
type: string
initial_client_public_ip:
type: string
initial_client_wifi_ssid:
type: string
client_local_router_ip:
type: string
session_uid:
type: string
user_account:
type: string
computer_id:
type: string
cvad_session_key:
type: string
UserMetadata:
type: object
properties:
orgId:
type: string
infraGuid:
type: string
region:
type: string
userId:
type: string
total:
type: integer
format: int64
limitPerPage:
type: integer
format: int32
currentPageNumber:
type: integer
format: int32
currentPageSize:
type: integer
format: int32
remaining:
type: integer
format: int64
userEmail:
type: string
truncated:
type: boolean
truncationLimit:
type: integer
format: int32
timeFrom:
type: string
timeTo:
type: string
SessionDetailsEventsResponse:
type: object
properties:
metadata:
$ref: '#/components/schemas/UserMetadata'
data:
$ref: '#/components/schemas/SessionDetailsResult'
SessionResourcesResult:
type: object
properties:
user_name:
type: string
logoff_time:
type: string
user_full_name:
type: string
session_id:
type: string
login_time:
type: string
logon_duration:
type: integer
format: int64
session_protocol_latency_avg:
type: integer
format: int64
initial_program:
type: string
initial_client_ip:
type: string
user_ad_ou:
type: string
initial_client_branch_name:
type: string
session_protocol_bandwidth_usage_avg:
type: integer
format: int64
session_protocol_bandwidth_usage_max:
type: integer
format: int64
rtt_avg:
type: integer
format: int64
session_protocol_latency_max:
type: integer
format: int64
cpu_usage_avg:
type: integer
format: int64
gpu_cpu_utilization_avg:
type: integer
format: int64
memory_usage_avg:
type: integer
format: int64
desktop_load_time:
type: integer
format: int64
group_policy_load_time:
type: integer
format: int64
io_usage_iops_avg:
type: integer
format: int64
disk_read_kbyte_per_sec_avg:
type: integer
format: int64
disk_write_kbyte_per_sec_avg:
type: integer
format: int64
logoff_flag:
type: string
machine_name:
type: string
domain_name:
type: string
user_account:
type: string
user_domain:
type: string
frames_per_second_avg:
type: integer
format: int64
app_load_time_avg:
type: integer
format: int64
total_session_latency_avg:
type: integer
format: int64
internet_latency_avg:
type: integer
format: int64
lan_latency_avg:
type: integer
format: int64
initial_client_name:
type: string
session_uid:
type: string
computer_id:
type: string
cvad_session_key:
type: string
SessionActivityResponse:
type: object
properties:
metadata:
$ref: '#/components/schemas/UserMetadata'
data:
type: array
items:
$ref: '#/components/schemas/SessionActivityResult'
SessionUxResponse:
type: object
properties:
metadata:
$ref: '#/components/schemas/UserMetadata'
data:
type: array
items:
$ref: '#/components/schemas/SessionUxResult'
Error:
type: object
properties:
message:
type: string
errorCode:
type: integer
format: int32
statusCode:
type: integer
format: int32
SessionTimelineResult:
type: object
properties:
session_uid:
type: string
session_id:
type: string
user_account:
type: string
server_name:
type: string
domain_name:
type: string
login_time:
type: string
format: date-time
logoff_time:
type: string
format: date-time
duration:
type: integer
format: int64
current_state:
$ref: '#/components/schemas/SessionState'
timeline:
type: array
items:
$ref: '#/components/schemas/SessionState'
SessionActivityResult:
type: object
properties:
username:
type: string
logoff_time:
type: string
user_full_name:
type: string
session_id:
type: string
login_time:
type: string
duration_in_seconds:
type: integer
format: int64
logon_duration:
type: integer
format: int64
session_protocol_latency_avg:
type: integer
format: int64
initial_program: {}
initial_client_ip:
type: string
logon_server:
type: string
user_ad_ou:
type: string
initial_client_branch_name:
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/controlup/refs/heads/main/openapi/controlup-session-api-openapi.yml