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).
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:
ScoutCreateHttp:
title: HTTP
allOf:
- $ref: '#/components/schemas/Hives'
- type: object
properties:
address:
type: string
format: url
description: The target URL for the HTTP request.
subType:
type: string
description: The Scout's sub-type. This indicates the type of network test the Scout performs.
enum:
- net_http
options:
$ref: '#/components/schemas/HttpExtras'
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'
ScoutCreateVmwareWsOne:
title: VMware Workspace One
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:
- vmware_w1
otp:
$ref: '#/components/schemas/OTP'
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
ScoutItem:
oneOf:
- $ref: '#/components/schemas/ScoutItemEuc'
- $ref: '#/components/schemas/ScoutItemNet'
- $ref: '#/components/schemas/ScoutItemApp'
type: object
title: Scout Properties
description: Details about the Scout.
properties:
scoutId:
type: integer
description: ID of the Scout.
scoutName:
type: string
description: The Scout's name.
interval:
type: integer
description: The interval (in minutes) of how often the Scout runs.
lastRun:
type: number
format: timestamp
description: The time the Scout was last run. Measured in Unix time.
createdAt:
type: string
format: datetime
description: The time the Scout was created. Formatted as yyyy-MM-dd HH-mm-ss.
disabled:
type: boolean
description: Whether the Scout is disabled.
tags:
description: Key-value pairs that are associated with the Scout. These can be used to organize your Scouts.
type: array
items:
type: object
properties:
key:
type: string
description: The name of the tag.
value:
type: string
description: The value of the tag.
ScoutCreatePing:
title: Ping
allOf:
- $ref: '#/components/schemas/HostnameAndIp'
- $ref: '#/components/schemas/Hives'
- type: object
properties:
subType:
type: string
description: The Scout's sub-type. This indicates the type of network test the Scout performs.
enum:
- net_ping
options:
$ref: '#/components/schemas/PingExtras'
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
WebTransactionFlow:
title: Web Transaction Step
description: 'A single step in the Web Transactions flow.
Each step has an `actionType` that dictates which of `locator` and `extras` you must supply, and what shape they take:
| `actionType` | `locator` | `extras` |
|---------------------|-------------------------|-------------------------------------------------|
| `click` | required | omit (or `null`) |
| `mouse_hover` | required | omit (or `null`) |
| `step_in_iframe` | required | omit (or `null`) |
| `mfa` | required | omit (or `null`) |
| `move_mouse` | omit (or `null`) | omit (or `null`) |
| `step_out_iframe` | omit (or `null`) | omit (or `null`) |
| `insert_text` | required | `{ text, isPassword? }` |
| `press_key` | omit (or `null`) | `{ key }` |
| `assert` | required | `{ text, operator? }` |
| `wait` | required | `{ expectedCondition, timeout? }` |
| `switch_tab` | omit (or `null`) | `{ tab }` |
'
type: object
required:
- stepNumber
- actionType
properties:
stepNumber:
type: integer
minimum: 1
description: Position of the step in the flow (1-based).
description:
type: string
description: Free-text description of the step.
maxLength: 80
nullable: true
actionType:
type: string
description: The action this step performs.
enum:
- click
- press_key
- assert
- insert_text
- wait
- move_mouse
- mouse_hover
- step_in_iframe
- step_out_iframe
- switch_tab
- mfa
locator:
description: How to locate the target DOM element. Required only for the `actionType` values marked "required" above.
nullable: true
type: object
required:
- type
- value
properties:
type:
type: string
description: Selector strategy.
enum:
- xpath
- css_selector
- js_path
value:
type: string
description: The selector expression itself (XPath / CSS selector / JS path).
extras:
description: 'Action-specific parameters. The exact shape depends on `actionType`; pass `null` or omit for actions that don''t take any.
'
nullable: true
oneOf:
- title: insert_text extras
type: object
required:
- text
properties:
text:
type: string
description: The text to type into the located element.
isPassword:
type: boolean
default: false
description: Mark the value as a password. Stored encrypted; not returned in GET responses.
- title: press_key extras
type: object
required:
- key
properties:
key:
type: string
description: The key to press (for example `Enter`, `Tab`, `Escape`).
- title: assert extras
type: object
required:
- text
properties:
text:
type: string
description: The substring expected to appear in the located element.
operator:
type: string
description: Comparison operator. `contains` is the only supported value today.
enum:
- contains
default: contains
- title: wait extras
type: object
required:
- expectedCondition
properties:
expectedCondition:
type: string
description: The DOM condition the Scout waits for before proceeding to the next step.
enum:
- exists
- visible
- visible_and_enabled
timeout:
type: integer
description: Maximum wait time in seconds.
minimum: 1
maximum: 180
default: 15
- title: switch_tab extras
type: object
required:
- tab
properties:
tab:
type: string
description: Which tab to switch to.
enum:
- last
- original
ScoutCreateEucDomain:
type: object
properties:
domain:
type: string
description: The domain used to access the gateway.
required:
- domain
OTP:
description: 'One-time password (OTP) information for the Scout. MFA is supported for all EUC Scout platforms except Citrix Storefront.
Visit [Multi-Factor Authentication](https://support.controlup.com/docs/mfa) for more details on how to configure MFA.
'
nullable: true
oneOf:
- title: TOTP | OTP
type: object
nullable: true
properties:
type:
type: string
description: 'The OTP method used. `totp` means that the Scout is registered as a TOTP device and will dynamically use the current OTP. `static` means that the Scout always uses the same static PIN. These methods are only available for single-step MFA.
'
enum:
- totp
- static
code:
type: string
description: The TOTP code or the static PIN, depending on `type`.
required:
- type
- code
- title: OTP phone call
type: object
nullable: true
properties:
type:
type: string
description: "The OTP method used. `phone` means that the Scout uses a phone call for authentication. This method is only available for dual-step MFA.\n\nYou must contact [Scoutbees Support](https://controlup.zendesk.com/hc/en-us/requests/new) to configure a phone number for phone authentication. You can [get a list of MFA users](https://scoutbees.io/honeycomb/v2#tag/MFAs/operation/honeycomb.api.get_org_mfas) that are configured with a phone number for authentication. \n"
enum:
- phone
phone:
type: string
description: Phone number used for phone call verification.
required:
- type
- phone
- title: OTP SMS
description: Single-step two-Factor authentication method
type: object
nullable: true
properties:
type:
type: string
description: 'The OTP method used. `sms` means that the Scout uses SMS to receive a passcode for authentication. This method is only available for dual-step MFA.
You must contact ControlUp Support to configure a phone number for SMS authentication. You can [get a list of MFA users](honeycombapiget_org_mfas) that are configured with a phone number for authentication.
'
enum:
- sms
phone:
type: string
description: Phone number used for SMS verification.
reset:
type: boolean
description: Set to `true` if your MFA vendor sends multiple passcodes in a single SMS. Set to `false` if your MFA vendor sends a single passcode per SMS.
default: false
required:
- type
- phone
ScoutCreateEuc:
title: EUC Scout
oneOf:
- $ref: '#/components/schemas/ScoutCreateCitrix'
- $ref: '#/components/schemas/ScoutCreateCitrixCloud'
- $ref: '#/components/schemas/ScoutCreateStorefront'
- $ref: '#/components/schemas/ScoutCreateVmware'
- $ref: '#/components/schemas/ScoutCreateVmwareWsOne'
- $ref: '#/components/schemas/ScoutCreateVmwareSecServer'
- $ref: '#/components/schemas/ScoutCreateAvd'
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'
required:
- address
- subType
- scoutName
- hiveId
- cloudHive
- name
- interval
- resource
- username
- password
HttpProxy:
description: Proxy information. A proxy server is only available if the Scout is running from a Custom Hive.
oneOf:
- type: object
title: No proxy
properties:
type:
type: string
description: '''none'' means that there is no proxy. The request is sent directly to the server.'
enum:
- none
- type: object
title: Inherited
properties:
type:
type: string
description: '''inherited'' means that the Scout uses the same proxy server data that is configured for the Custom Hive running the Scout.'
enum:
- inherited
- type: object
title: Custom
properties:
type:
type: string
description: '''custom'' means that a proxy server is configured for the Scout.'
enum:
- custom
address:
type: string
format: url
description: The address of the proxy server.
port:
description: The port used for the proxy server.
type: integer
minimum: 1
maximum: 65535
default: 1080
protocol:
description: The HTTP protocol.
type: string
enum:
- http
- https
username:
description: The username for the proxy server.
type: string
password:
description: The password for the proxy server.
type: string
format: password
writeOnly: true
ScoutEditMail:
title: Mail
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. Cannot be edited without supplying a fresh access token in `password`.
maxLength: 100
password:
type: object
description: OAuth token data returned by the Entra ID user-consent flow. Must contain `accessToken` (delegated). Refresh-token fields obtained during consent should be included so the scout can renew without re-prompting.
writeOnly: true
options:
$ref: '#/components/schemas/MailExtras'
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
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
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
# --- 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