ControlUp Applications API

openapi: 3.2.0
info:
  title: VDI & DAAS Applications API
  version: 1.0.0
  description: Applications usage reports
servers:
- url: https://api.controlup.com/historical
security:
- bearer-jwt:
  - read
  - write
tags:
- name: Applications
  description: Applications usage reports
paths:
  /v1/applications/usage/single:
    get:
      tags:
      - Applications
      summary: Get usage details for an application
      description: Returns usage details for the specified application including usage per machine, per user account, and the peak number of concurrent instances throughout the search period. The granularity of the peak concurrent instances depends on the length of the search period, and how far back in the past the search period is.
      operationId: getAppUsageSingle
      parameters:
      - name: appName
        in: query
        description: The name of the application
        required: true
        schema:
          type: string
        example: chrome.exe
      - name: appVersion
        in: query
        description: Only return usage details for the specified application version number.
        required: false
        schema:
          type: string
        example: 1.0.0
      - 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: _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/HistoricalSingleResponseAppUsageSingleResult'
            application/xml:
              schema:
                $ref: '#/components/schemas/HistoricalSingleResponseAppUsageSingleResult'
        '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/applications/usage/all:
    get:
      tags:
      - Applications
      summary: Get usage details for all applications
      description: Returns usage details for all applications (number of unique users and peak number of concurrent users) throughout the search period. The granularity of the returned data depends on the length of the search period, and how far back in the past the search period is. Only applications with at least 1 user are returned. Usage details are returned per application version.
      operationId: getAppUsage
      parameters:
      - name: _timeFrom
        in: query
        description: 'Start date of the search period in the format: YYYY-MM-DD'
        required: true
        schema:
          type: string
          format: date
        example: '2025-02-01'
      - name: _timeTo
        in: query
        description: 'End date of the search period in the format: YYYY-MM-DD'
        required: true
        schema:
          type: string
          format: date
        example: '2025-02-02'
      - 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/HistoricalListResponseAppUsageAllResult'
            application/xml:
              schema:
                $ref: '#/components/schemas/HistoricalListResponseAppUsageAllResult'
        '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/applications/statistics:
    get:
      tags:
      - Applications
      summary: Get application statistics
      description: Returns usage details and resource consumption statistics for all applications (per version number). Statistics are aggregated either weekly (Monday-Sunday) or monthly, depending on the timeFrame parameter. Visit the <a href='https://support.controlup.com/docs/application-statistics-report' target='_blank'>App Statistics Report</a> documentation for column descriptions and more details.
      operationId: getAppStats
      parameters:
      - name: timeFrame
        in: query
        description: Aggregate statistics either weekly (Monday-Sunday) or monthly.
        required: true
        schema:
          type: string
          description: Aggregate statistics either weekly (Monday-Sunday) or monthly.
          enum:
          - 1W
          - 1M
      - name: datetime
        in: query
        description: Return statistics around the specified date and time. If timeFrame is set to 1W (1 week), then the endpoint returns statistics for the week (Monday-Sunday) that the date is within. If timeFrame is set to 1M (1 month), then the endpoint returns statistics for the month that the date is within. For example, if the specified date and time is on Saturday the 6th and timeFrame = 1W, then the endpoint returns aggregated statistics from Monday the 1st to Sunday the 7th.
        required: true
        schema:
          type: string
        example: '2025-02-01T00:00:00.000Z'
      - name: folderPath
        in: query
        description: Limits the scope of the returned application statistics to machines located under the specified full folder path within the ControlUp VDI organizational tree. Path must start with the root organization name (e.g., controlup\hq\financevdi)
        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/AppStatsResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/AppStatsResponse'
        '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:
    AppStatsResponse:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/UserMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/ApplicationStatistics'
    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
    AppUsageSingleResult:
      type: object
      properties:
        computer_grouping:
          type: array
          items:
            $ref: '#/components/schemas/ByComputer'
        user_grouping:
          type: array
          items:
            $ref: '#/components/schemas/ByUser'
        concurrent_instances:
          type: array
          items:
            $ref: '#/components/schemas/ConcurrentInstances'
        unique_users:
          type: integer
          format: int32
    ByUser:
      type: object
      properties:
        user_account:
          type: string
        total_instances:
          type: integer
          format: int32
        unique_machines:
          type: integer
          format: int32
        process_name:
          type: string
        last_use_time:
          type: string
          format: date-time
        process_version:
          type: string
    AppUsageAllResult:
      type: object
      properties:
        application_name:
          type: string
        application_version:
          type: string
        peak_concurrency:
          type: integer
          format: int32
        unique_user_count:
          type: integer
          format: int32
        update_time:
          type: string
          format: date-time
    HistoricalSingleResponseAppUsageSingleResult:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/UserMetadata'
        data:
          $ref: '#/components/schemas/AppUsageSingleResult'
    HistoricalErrorResponse:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/UserMetadata'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    ByComputer:
      type: object
      properties:
        computer_name:
          type: string
        unique_users:
          type: integer
          format: int32
        total_instances:
          type: integer
          format: int32
        process_name:
          type: string
        process_version:
          type: string
    HistoricalListResponseAppUsageAllResult:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/UserMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/AppUsageAllResult'
    ConcurrentInstances:
      type: object
      properties:
        process_name:
          type: string
        process_version:
          type: string
        peak_concurrency:
          type: integer
          format: int32
        date_time:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        message:
          type: string
        errorCode:
          type: integer
          format: int32
        statusCode:
          type: integer
          format: int32
    ApplicationStatistics:
      type: object
      properties:
        applicationName:
          type: string
        processVersion:
          type: string
        processNameId:
          type: string
        processVersionId:
          type: string
        uniqueUsers:
          type: integer
          format: int64
        uniqueUsersTrend:
          type: integer
          format: int64
        peakConcurrentInstances:
          type: integer
          format: int64
        averageLoadTime:
          type: integer
          format: int64
        averageCpuUsage:
          type: integer
          format: int64
        averageGpuUsage:
          type: integer
          format: int64
        averageMemoryConsumption:
          type: integer
          format: int64
        averageReadIoUsage:
          type: integer
          format: int64
        averageWriteIoUsage:
          type: integer
          format: int64
        averageTotalIoUsage:
          type: integer
          format: int64
        totalInstances:
          type: integer
          format: int64
        uniqueMachines:
          type: integer
          format: int64
        cpuPercentile:
          type: integer
          format: int64
  securitySchemes:
    bearer-jwt:
      type: http
      scheme: bearer
x-readme:
  proxy-enabled: false
  explorer-enabled: true
  samples-languages:
  - shell
  - powershell
  - node
  - javascript
  - python
  - c
  - clojure
  - cplusplus
  - csharp
  - http
  - go
  - java
  - json
  - kotlin
  - objectivec
  - ocaml
  - php
  - r
  - ruby
  - shell
  - swift