ControlUp Scouts API

openapi: 3.2.0
info:
  title: Synthetic Monitoring Scouts API
  version: 2.0.0
  x-logo:
    url: https://app.scoutbees.io/static/media/scoutbees_new.ef578490.png
  termsOfService: https://www.controlup.com/privacy-policy/controlup-eula/
  description: 'Scouts are the proactive tests that you configure to monitor the availability and health of various resources. There are different types of Scouts, depending on the type of resource you want to test. Within each type, there are sub-types which determine which test is performed and the available test configuration options.


    Scouts are initiated from Hives, which are either hosted in the cloud (Cloud Hives), or installed on-premises (Custom Hives).

    '
servers:
- url: https://api.controlup.com/synthetic-monitoring/v2/
tags:
- name: Scouts
  description: 'Scouts are the proactive tests that you configure to monitor the availability and health of various resources. There are different types of Scouts, depending on the type of resource you want to test. Within each type, there are sub-types which determine which test is performed and the available test configuration options.


    Scouts are initiated from Hives, which are either hosted in the cloud (Cloud Hives), or installed on-premises (Custom Hives).

    '
paths:
  /scouts:
    get:
      summary: List all Scouts
      description: Returns a list of your Scouts.
      operationId: app.get_scouts
      security:
      - ApiKeyAuth:
        - read
      parameters:
      - in: query
        name: hiveId
        description: Only return Scouts running from the Custom Hives specified by these hive IDs.
        style: form
        explode: false
        schema:
          type: array
          example: 1,2
          items:
            type: integer
            format: int32
            minimum: 1
      - in: query
        name: cloudHive
        description: Only return Scouts running from the Cloud Hives specified by these hive IDs.
        style: form
        explode: false
        schema:
          type: array
          example: 1,2
          items:
            type: integer
            format: int32
            minimum: 1
      - in: query
        name: scoutName
        description: Filter by Scout name (partial match).
        schema:
          type: string
      - $ref: '#/components/parameters/Type'
      - $ref: '#/components/parameters/SubType'
      - in: query
        description: Filter the list based on the interval (in minutes) of how often a Scout runs.
        name: interval
        schema:
          type: integer
      - in: query
        name: disabled
        description: Use this parameter to only return disabled Scouts. By default, only enabled Scouts are returned.
        schema:
          type: boolean
          enum:
          - 0
          - 1
          default: 0
      - in: query
        name: username
        description: Only return Scouts that use this username to access the resource. This only applies to EUC Scouts.
        schema:
          type: string
      - in: query
        name: page
        description: The page of Scouts to be returned. Each page contains up to 100 Scouts. If your request returns more than 100 Scouts, then the response is paginated.
        schema:
          type: integer
      - in: query
        name: tags
        description: Only return Scouts with the specified tag IDs. You can use [GET /v1/organizations/{orgId}/tags](orgtagspubliccontroller_getall) to get the IDs of each tag.
        style: form
        explode: false
        schema:
          type: array
          example: 07725341-3335-4f4a-a6d7-f64302546c7e,e3d5e40e-b0d5-4e59-b599-0f68834f4de9
          items:
            type: string
            format: uuid
      tags:
      - Scouts
      responses:
        '200':
          $ref: '#/components/responses/ScoutList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      x-codeSamples:
      - lang: cURL
        source: 'curl -X GET ''https://api.scoutbees.io/honeycomb/v2/scouts?cloudHive=2&type=euc&username=TestBot1'' \

          -H ''x-scoutbees-key: API-key-here''

          '
    post:
      summary: Create a Scout
      description: Create a Scout to test EUC or network resources. Creating a Scout uses credits on your account. If you disable or delete the Scout, then the credits are returned to your account. See [License Information](https://support.controlup.com/docs/license-information) for more details.
      operationId: app.create_scout
      security:
      - ApiKeyAuth:
        - write
      requestBody:
        $ref: '#/components/requestBodies/ScoutCreate'
      tags:
      - Scouts
      responses:
        '201':
          description: Scout created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: Message indicating whether the request was successful.
                    type: string
                  scoutId:
                    description: The ID of the recently created Scout.
                    type: integer
                  scoutDetails:
                    description: The number of credits used to create the Scout.
                    type: integer
                  availableCredits:
                    description: The number of remaining credits on your account.
                    type: integer
                  totalCredits:
                    description: The total number of credits that have been purchased for your account.
                    type: integer
                example:
                  message: Scout has been created.
                  scoutDetails: 1000
                  availableCredits: 30000
                  totalCredits: 75000
                  scoutId: 1000
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      x-codeSamples:
      - lang: cURL
        source: "curl -X POST 'https://api.scoutbees.io/honeycomb/v2/scouts' \\\n-H 'x-scoutbees-key: API-key-here' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"cloudHive\": 2,\n    \"subType\": \"citrix_gateway\",\n    \"address\": \"https://ns.example.com\",\n    \"scoutName\": \"NetScaler sample\",\n    \"interval\": 5,\n    \"resource\": \"Calculator\",\n    \"username\": \"TestBot1\",\n    \"password\": \"Swordfish\",\n    \"otp\": {\n        \"type\": \"static\",\n        \"code\": \"872960\"\n    },\n    \"options\": {\n        \"loginAttempts\": 2\n    }\n}'\n"
  /scouts/{scoutId}:
    get:
      summary: Get Scout info
      description: Returns the details of a specific Scout, and a summary of it's test results. By default, the summary uses test results from the last 24 hours.
      operationId: app.get_scout_by_id
      security:
      - ApiKeyAuth:
        - read
      parameters:
      - name: scoutId
        in: path
        description: ID of the Scout.
        required: true
        schema:
          type: integer
      - name: start
        in: query
        description: Start date and time of test results used for the summary.
        schema:
          type: string
          format: date-time
        example: '2021-01-01 13:21:55'
      - name: end
        in: query
        description: End date and time of the test results used for the summary.
        schema:
          type: string
          format: date-time
        example: '2021-02-01 10:24:55'
      tags:
      - Scouts
      responses:
        '200':
          $ref: '#/components/responses/ScoutItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      x-codeSamples:
      - lang: cURL
        source: 'curl -X GET ''https://api.scoutbees.io/honeycomb/v2/scouts/10354'' \

          -H ''x-scoutbees-key: API-key-here''

          '
    put:
      summary: Edit Scout
      description: Edits an existing Scout. Any parameters passed in this call will be updated to the new values. Unused parameters will not be changed.
      operationId: app.edit_scout
      security:
      - ApiKeyAuth:
        - write
      parameters:
      - name: scoutId
        in: path
        description: ID of the Scout.
        required: true
        schema:
          type: integer
      requestBody:
        $ref: '#/components/requestBodies/ScoutEdit'
      tags:
      - Scouts
      responses:
        '204':
          description: Scout was edited successfully
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      x-codeSamples:
      - lang: cURL
        source: "curl -X PUT 'https://api.scoutbees.io/honeycomb/v2/scouts/10354' \\\n-H 'x-scoutbees-key: API-key-here' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"interval\": 10\n}'\n"
    delete:
      summary: Delete Scout
      description: 'Deletes a Scout. This cannot be undone. Historical test result data for the Scout will still be available.


        The credits used to create the Scout will be returned to your account.

        '
      operationId: app.delete_scout
      security:
      - ApiKeyAuth:
        - write
      parameters:
      - name: scoutId
        in: path
        description: ID of the Scout.
        required: true
        schema:
          type: integer
      tags:
      - Scouts
      responses:
        '204':
          description: Scout deleted
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      x-codeSamples:
      - lang: cURL
        source: 'curl -X DELETE ''https://api.scoutbees.io/honeycomb/v2/scouts/10354'' \

          -H ''x-scoutbees-key: API-key-here''

          '
  /scouts/{scoutId}/disabled:
    post:
      summary: Enable/disable Scout
      description: "Enables or disables an existing Scout. A Scout only performs tests while it is enabled. \n\nEnabling a Scout uses credits on your account. Disabling a Scout returns the credits.\n"
      operationId: app.disable_scout
      security:
      - ApiKeyAuth:
        - write
      parameters:
      - name: scoutId
        in: path
        description: ID of the Scout.
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                disabled:
                  description: Set to `true` to disable the Scout. Set to `false` to enable the Scout.
                  type: boolean
              required:
              - disabled
      tags:
      - Scouts
      responses:
        '204':
          description: Scout enabled/disabled
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      x-codeSamples:
      - lang: cURL
        source: "curl -X POST 'https://api.scoutbees.io/honeycomb/v2/scouts/10354/disabled' \\\n-H 'x-scoutbees-key: API-key-here' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"disabled\": true\n}'\n"
components:
  schemas:
    MarshmallowError:
      type: object
      properties:
        errors:
          type: object
          items:
            type: array
            items:
              type: string
      example:
        errors:
          name:
          - Missing required data.
          period:
          - 'Must be one of: [ 1, 2, 3, 5, 10, 15, 30, 60 ]'
    ScoutEditShell:
      title: Shell
      allOf:
      - type: object
        properties:
          hives:
            type: object
            description: Custom Hives that run the Scout. Shell Scouts do not support Cloud Hives.
            properties:
              custom:
                type: array
                description: Custom Hive IDs.
                minItems: 1
                items:
                  type: integer
                  format: int32
          address:
            type: string
            description: The executable the Scout runs on the host where its Custom Hive is installed.
          options:
            $ref: '#/components/schemas/ShellExtras'
    ScoutEditEntraId:
      title: Entra ID
      allOf:
      - $ref: '#/components/schemas/Hives'
      - type: object
        properties:
          address:
            type: string
            description: The Entra ID tenant ID the Scout authenticates against.
          username:
            type: string
            description: Email of the user the Scout authenticates as.
            maxLength: 100
          password:
            type: object
            description: Authentication credentials. For `application` auth, supply `clientId` and `clientSecret`. For `oauth` auth, supply the OAuth token data returned by the consent flow.
            writeOnly: true
          options:
            $ref: '#/components/schemas/EntraIdExtras'
    EucExtras:
      description: Additional options.
      type: object
      properties:
        sessionTimeout:
          type: integer
          description: The maximum wait time (in seconds) for the session to be fully ready.
          minimum: 10
          maximum: 450
        connectionTimeout:
          type: integer
          description: The maximum wait time (in seconds) for the connection phase to the session.
          minimum: 10
          maximum: 300
        loginAttempts:
          type: integer
          description: The maximum number of allowed unssuccessful login attempts.
          minimum: 1
          maximum: 5
    TracerouteExtras:
      description: Additional options.
      title: Traceroute options
      oneOf:
      - $ref: '#/components/schemas/ProtocolICMP'
      - $ref: '#/components/schemas/Protocols'
      type: object
      properties:
        timeout:
          description: The maximum wait time (in seconds).
          type: number
          format: float
          minimum: 0.001
          maximum: 3.6
          default: 1
        minttl:
          description: The minimum time to live (TTL) in ms.
          type: integer
          minimum: 1
          maximum: 255
          default: 1
        maxttl:
          description: The maximum time to live (TTL) in ms.
          type: integer
          minimum: 1
          maximum: 255
          default: 30
        numPaths:
          type: integer
          description: The maximum number of paths.
          minimum: 1
          maximum: 10
          default: 3
    ScoutSummary:
      title: Summary
      description: Statistics about the Scout's test results.
      type: object
      properties:
        startTime:
          type: string
          format: date-time
          description: Start date and time of the test results used for summary statistics.
        endTime:
          type: string
          format: date-time
          description: End date and time of the test results used for summary statistics.
        successfulTests:
          type: integer
          description: The number of successful tests within the search period.
        totalTests:
          type: integer
          description: The total number of tests within the search period.
        totalSuccess:
          type: number
          format: float
          description: Percentage of tests that are successful within the search period.
      oneOf:
      - title: EUC Scout
        type: object
        properties:
          sessionReadyAvg:
            type: number
            format: float
            description: Average time for the session to be ready in seconds.
          sessionReadyMax:
            type: number
            format: float
            description: Maximum time for the session to be ready in seconds.
          sessionReadyMedian:
            type: number
            format: float
            description: Median time for the session to be ready in seconds.
          sessionReady95Percentile:
            type: number
            format: float
            description: 95th percentile of the time for the session to be ready in seconds.
          authPhaseAvg:
            type: number
            format: float
            description: Average authentication time in seconds.
          enumTimeAvg:
            type: number
            format: float
            description: Average enumeration time in seconds.
          icaTimeAvg:
            type: number
            format: float
            description: Average ICA download time in seconds.
          connPhaseAvg:
            type: number
            format: float
            description: Average connection time in seconds.
          initAvg:
            type: number
            format: float
            description: Average session initialization time in seconds.
          readyAvg:
            type: number
            format: float
            description: Average session handoff (ready) duration in seconds.
      - title: Network Scout
        oneOf:
        - type: object
          title: Ping
          properties:
            avgRttAvg:
              type: number
              format: float
              description: Average response time in ms.
            avgRttMax:
              type: number
              format: float
              description: Maximum response time in ms.
            avgRttMedian:
              type: number
              format: float
              description: Median response time in ms.
            avgRtt95Percentile:
              type: number
              format: float
              description: 95th percentile of the response time in ms.
            jitterAvg:
              type: number
              format: float
              description: Average jitter in ms.
        - type: object
          title: DNS
          properties:
            runtimeAvg:
              type: number
              format: float
              description: Average response time in ms.
            runtimeMax:
              type: number
              format: float
              description: Maximum response time in ms.
            runtimeMedian:
              type: number
              format: float
              description: Median response time in ms.
            runtime95Percentile:
              type: number
              format: float
              description: 95th percentile of the response time in ms.
        - type: object
          title: Traceroute
          properties:
            avgRttAvg:
              type: number
              format: float
              description: Average response time in ms.
            avgRttMax:
              type: number
              format: float
              description: Maximum response time in ms.
            avgRttMedian:
              type: number
              format: float
              description: Median response time in ms.
            avgRtt95Percentile:
              type: number
              format: float
              description: 95th percentile the response time in ms.
        - type: object
          title: HTTP/S
          properties:
            latencyAvg:
              type: number
              format: float
              description: Average latency in ms.
            latencyMax:
              type: number
              format: float
              description: Maximum latency in ms.
            latencyMedian:
              type: number
              format: float
              description: Median latency in ms.
            latency95Percentile:
              type: number
              format: float
              description: 95th percentile of the latency in ms.
            namelookupTimeAvg:
              type: number
              format: float
              description: Average name lookup time in ms.
            connectTimeAvg:
              type: number
              format: float
              description: Average connection time in ms.
            tlsHandshakeTimeAvg:
              type: number
              format: float
              description: Average TLS handshake time in ms.
            responseTimeAvg:
              type: number
              format: float
              description: Average response time in ms.
            ttfbAvg:
              type: number
              format: float
              description: Average time to first byte in ms.
            redirectTimeAvg:
              type: number
              format: float
              description: Average redirect time in ms.
        - type: object
          title: Shell
          properties:
            runtimeAvg:
              type: number
              format: float
              description: Average shell command execution duration in ms.
            runtimeMax:
              type: number
              format: float
              description: Maximum shell command execution duration in ms.
            runtimeMedian:
              type: number
              format: float
              description: Median shell command execution duration in ms.
            runtime95Percentile:
              type: number
              format: float
              description: 95th percentile of the shell command execution duration in ms.
        - type: object
          title: Entra ID
          properties:
            userQueryDurationAvg:
              type: number
              format: float
              description: Average duration of the user lookup query against Entra ID, in ms.
            userQueryDurationMax:
              type: number
              format: float
              description: Maximum duration of the user lookup query against Entra ID, in ms.
            userQueryDurationMedian:
              type: number
              format: float
              description: Median duration of the user lookup query against Entra ID, in ms.
            userQueryDuration95Percentile:
              type: number
              format: float
              description: 95th percentile of the user lookup query duration, in ms.
            queryDurationAvg:
              type: number
              format: float
              description: Average duration of the directory query against Entra ID, in ms.
      - title: Application Scout
        oneOf:
        - type: object
          title: Siteload
          properties:
            durationAvg:
              type: number
              format: float
              description: Average page load duration in ms.
            durationMax:
              type: number
              format: float
              description: Maximum page load duration in ms.
            durationMedian:
              type: number
              format: float
              description: Median page load duration in ms.
            duration95Percentile:
              type: number
              format: float
              description: 95th percentile of the page load duration in ms.
            ttfbAvg:
              type: number
              format: float
              description: Average time to first byte in ms.
            firstPaintAvg:
              type: number
              format: float
              description: Average time until the first paint event in ms.
            contentfulPaintAvg:
              type: number
              format: float
              description: Average time until the first contentful paint event in ms.
            domCompleteAvg:
              type: number
              format: float
              description: Average time until the DOM reached the complete state in ms.
        - type: object
          title: Microsoft Teams
          properties:
            avgLatencyAvg:
              type: number
              format: float
              description: Average round-trip latency to the Teams relay in ms.
            avgLatencyMax:
              type: number
              format: float
              description: Maximum round-trip latency to the Teams relay in ms.
            avgLatencyMedian:
              type: number
              format: float
              description: Median round-trip latency to the Teams relay in ms.
            avgLatency95Percentile:
              type: number
              format: float
              description: 95th percentile of the round-trip latency in ms.
            avgJitterAvg:
              type: number
              format: float
              description: Average jitter observed during the media test in ms.
            packetsLossAvg:
              type: number
              format: float
              description: Average packet loss ratio across tests, as a percentage.
            httpLatencyAvg:
              type: number
              format: float
              description: Average total time to receive the HTTP signaling response in ms.
        - type: object
          title: Web Transactions
          properties:
            totalDurationAvg:
              type: number
              format: float
              description: Average total transaction duration including all steps in ms.
            totalDurationMax:
              type: number
              format: float
              description: Maximum total transaction duration in ms.
            totalDurationMedian:
              type: number
              format: float
              description: Median total transaction duration in ms.
            totalDuration95Percentile:
              type: number
              format: float
              description: 95th percentile of the total transaction duration in ms.
            stepsDurationAvg:
              type: number
              format: float
              description: Average cumulative duration of the user-defined steps after the initial page load, in ms.
        - type: object
          title: Mail
          properties:
            deliveryDurationAvg:
              type: number
              format: float
              description: Average end-to-end mail delivery duration in ms.
            deliveryDurationMax:
              type: number
              format: float
              description: Maximum end-to-end mail delivery duration in ms.
            deliveryDurationMedian:
              type: number
              format: float
              description: Median end-to-end mail delivery duration in ms.
            deliveryDuration95Percentile:
              type: number
              format: float
              description: 95th percentile of the end-to-end mail delivery duration in ms.
            emailServerProcessDurationAvg:
              type: number
              format: float
              description: Average time spent processing on the customer email server, in ms.
            clientToEmailServerDurationAvg:
              type: number
              format: float
              description: Average duration from client send to the customer email server, in ms.
            emailServerToDestinationDurationAvg:
              type: number
              format: float
              description: Average duration from the customer email server to the destination mailbox, in ms.
            deliveryDurationToEmailServerAvg:
              type: number
              format: float
              description: Average delivery duration up to the customer email server, in ms.
    EntraIdExtras:
      title: Entra ID options
      description: Additional options for the Entra ID (Azure AD) Scout.
      type: object
      properties:
        authentication:
          type: string
          description: The authentication flow used to acquire a token against the Entra ID tenant.
          enum:
          - application
          - oauth
        connectStatus:
          type: boolean
          description: Whether the Scout verifies the tenant connection status.
          default: true
        querySignedInTestUser:
          type: boolean
          description: Whether the Scout queries the signed-in test user as part of the test.
          default: true
        clientSecretLast6Chars:
          type: string
          description: The last 6 characters of the client secret, retained for identification only. Set by the server when `authentication` is `application`; user-supplied values are ignored.
          readOnly: true
      required:
      - authentication
    ScoutCreateWebTransactions:
      title: Web Transactions
      description: Drives a real browser through a list of steps and reports timing and navigation metrics for each step.
      allOf:
      - $ref: '#/components/schemas/Hives'
      - type: object
        properties:
          subType:
            type: string
            description: The Scout's sub-type.
            enum:
            - web_transactions
          address:
            type: string
            format: url
            description: The starting URL for the transaction flow.
          transactionFlows:
            type: array
            description: Ordered list of steps the Scout executes against the target site.
            items:
              $ref: '#/components/schemas/WebTransactionFlow'
          otp:
            $ref: '#/components/schemas/OTP'
          options:
            $ref: '#/components/schemas/WebTransactionsExtras'
        required:
        - address
        - transactionFlows
    CloudOrCustomHive:
      oneOf:
      - title: Cloud Hive
        type: object
        properties:
          cloudHive:
            type: integer
            format: int32
            description: ID of the Cloud Hive from which the Scout will run.
      - title: Custom Hive
        type: object
        properties:
          hiveId:
            type: integer
            format: int32
            description: ID of the Custom Hive from which the Scout will run.
    ScoutEditEuc:
      title: Edit EUC Scout
      type: object
      properties:
        address:
          type: string
          format: url
          description: The address of the gateway that the Scout accesses.
        scoutName:
          type: string
          description: The Scout's name.
        interval:
          type: integer
          description: The interval (in minutes) of how often the Scout runs.
          enum:
          - 5
          - 10
          - 15
          - 30
          - 60
        resource:
          type: string
          description: The published resource that the Scout accesses and tests.
        username:
          type: string
          description: The username used to access the gateway.
        password:
          type: string
          description: The password used to access the gateway.
          writeOnly: true
        options:
          $ref: '#/components/schemas/EucExtras'
      allOf:
      - $ref: '#/components/schemas/CloudOrCustomHive'
      - type: object
        properties:
          domain:
            type: string
            description: 'The domain used to access the gateway. This is only available for the following sub-types: `citrix_cloud`, `vmware_horizon`, `vmware_secsrv`.'
    ScoutCreateAvd:
      title: Azure Virtual Desktop
      allOf:
      - $ref: '#/components/schemas/CloudOrCustomHive'
      - type: object
        properties:
          subType:
            type: string
            description: The Scout's sub-type. This indicates the EUC platform that the Scout accesses.
            enum:
            - avd
          address:
            type: string
            description: Optional gateway address. For AVD the resource itself identifies the target, so this field is allowed to be omitted.
            nullable: true
          otp:
            $ref: '#/components/schemas/OTP'
    ProtocolICMP:
      title: ICMP
      properties:
        protocol:
          description: 'The protocol used. By default, the scout uses the `ICMP` protocol.

            '
          type: string
          enum:
          - ICMP
          default: ICMP
        payload:
          description: The payload size (in bytes). The `payload` must be 32 bytes for the ICMP `protocol`.
          type: integer
          enum:
          - 32
    ScoutCreatePing:
      title: Ping
      allOf:
      - $ref: '#/components/schemas/HostnameAndIp'
      - $ref: '#/components/schemas/Hives'
      - type: object
        properties:
          subType:
            type: string
            description: The Scout

# --- truncated at 32 KB (89 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/controlup/refs/heads/main/openapi/controlup-scouts-api-openapi.yml