Create a monitor

POST /api/synthetics/monitors

Create a new monitor with the specified attributes. A monitor can be one of the following types: HTTP, TCP, ICMP, or Browser. The required and default fields may vary based on the monitor type. You must have all privileges for the Synthetics feature in the Observability section of the Kibana feature privileges.

application/json

Body object Required

The request body should contain the attributes of the monitor you want to create. The required and default fields differ depending on the monitor type.

alert object

The alert configuration. The default is { status: { enabled: true }, tls: { enabled: true } }.
enabled boolean

Specify whether the monitor is enabled.

Default value is true.
labels object

Key-value pairs of labels to associate with the monitor. Labels can be used for filtering and grouping monitors.
Hide labels attribute Show labels attribute object
- * string Additional properties
locations array[string]
The location to deploy the monitor. Monitors can be deployed in multiple locations so that you can detect differences in availability and response times across those locations. To list available locations you can:
- Run the elastic-synthetics locations command with the deployment's Kibana URL.
- Go to Synthetics > Management and click Create monitor. Locations will be listed in Locations.
name string Required

The monitor name.
namespace string

The namespace field should be lowercase and not contain spaces. The namespace must not include any of the following characters: *, \, /, ?, ", <, >, |, whitespace, ,, #, :, or -.

Default value is default.
params string

The monitor parameters.
private_locations array[string]
The private locations to which the monitors will be deployed. These private locations refer to locations hosted and managed by you, whereas locations are hosted by Elastic. You can specify a private location using the location's name. To list available private locations you can:
- Run the elastic-synthetics locations command with the deployment's Kibana URL.
- Go to Synthetics > Settings and click Private locationsr. Private locations will be listed in the table.
You can provide locations or private_locations or both. At least one is required.
retest_on_failure boolean

Turn retesting for when a monitor fails on or off. By default, monitors are automatically retested if the monitor goes from "up" to "down". If the result of the retest is also "down", an error will be created and if configured, an alert sent. The monitor will then resume running according to the defined schedule. Using retest_on_failure can reduce noise related to transient problems.

Default value is true.
schedule number

The monitor's schedule in minutes. Supported values are 1, 3, 5, 10, 15, 30, 60, 120, and 240. The default value is 3 minutes for HTTP, TCP, and ICMP monitors. The default value is 10 minutes for Browser monitors.
service.name string

The APM service name.
tags array[string]

An array of tags.
timeout number

The monitor timeout in seconds. The monitor will fail if it doesn't complete within this time.

Default value is 16.
ignore_https_errors boolean

Ignore HTTPS errors.

Default value is false.
inline_script string Required

The inline script.
playwright_options object

Playwright options.
screenshots string

The screenshot option.

Values are on, off, or only-on-failure. Default value is on.
synthetics_args array

Synthetics agent CLI arguments.
type string Required

The monitor type.

Value is browser.

alert object

The alert configuration. The default is { status: { enabled: true }, tls: { enabled: true } }.
enabled boolean

Specify whether the monitor is enabled.

Default value is true.
labels object

Key-value pairs of labels to associate with the monitor. Labels can be used for filtering and grouping monitors.
Hide labels attribute Show labels attribute object
- * string Additional properties
locations array[string]
The location to deploy the monitor. Monitors can be deployed in multiple locations so that you can detect differences in availability and response times across those locations. To list available locations you can:
- Run the elastic-synthetics locations command with the deployment's Kibana URL.
- Go to Synthetics > Management and click Create monitor. Locations will be listed in Locations.
name string Required

The monitor name.
namespace string

The namespace field should be lowercase and not contain spaces. The namespace must not include any of the following characters: *, \, /, ?, ", <, >, |, whitespace, ,, #, :, or -.

Default value is default.
params string

The monitor parameters.
private_locations array[string]
The private locations to which the monitors will be deployed. These private locations refer to locations hosted and managed by you, whereas locations are hosted by Elastic. You can specify a private location using the location's name. To list available private locations you can:
- Run the elastic-synthetics locations command with the deployment's Kibana URL.
- Go to Synthetics > Settings and click Private locationsr. Private locations will be listed in the table.
You can provide locations or private_locations or both. At least one is required.
retest_on_failure boolean

Turn retesting for when a monitor fails on or off. By default, monitors are automatically retested if the monitor goes from "up" to "down". If the result of the retest is also "down", an error will be created and if configured, an alert sent. The monitor will then resume running according to the defined schedule. Using retest_on_failure can reduce noise related to transient problems.

Default value is true.
schedule number

The monitor's schedule in minutes. Supported values are 1, 3, 5, 10, 15, 30, 60, 120, and 240. The default value is 3 minutes for HTTP, TCP, and ICMP monitors. The default value is 10 minutes for Browser monitors.
service.name string

The APM service name.
tags array[string]

An array of tags.
timeout number

The monitor timeout in seconds. The monitor will fail if it doesn't complete within this time.

Default value is 16.
check objects

The check request settings.
ipv4 boolean

If true, ping using the ipv4 protocol.

Default value is true.
ipv6 boolean

If true, ping using the ipv6 protocol.

Default value is true.
max_redirects number

The maximum number of redirects to follow.

Default value is 0.
mode string

The mode of the monitor. If it is all, the monitor pings all resolvable IPs for a hostname. If it is any, the monitor pings only one IP address for a hostname. If you're using a DNS-load balancer and want to ping every IP address for the specified hostname, you should use all.

Values are all or any. Default value is any.
password string

The password for authenticating with the server. The credentials are passed with the request.
proxy_headers object

Additional headers to send to proxies during CONNECT requests.
proxy_url string

The URL of the proxy to use for this monitor.
response object

Controls the indexing of the HTTP response body contents to the http.response.body.contents field.
ssl object

The TLS/SSL connection settings for use with the HTTPS endpoint. If you don't specify settings, the system defaults are used.
type string Required

The monitor type.

Value is http.
url string Required

The URL to monitor.
username string

The username for authenticating with the server. The credentials are passed with the request.

alert object

The alert configuration. The default is { status: { enabled: true }, tls: { enabled: true } }.
enabled boolean

Specify whether the monitor is enabled.

Default value is true.
labels object

Key-value pairs of labels to associate with the monitor. Labels can be used for filtering and grouping monitors.
Hide labels attribute Show labels attribute object
- * string Additional properties
locations array[string]
The location to deploy the monitor. Monitors can be deployed in multiple locations so that you can detect differences in availability and response times across those locations. To list available locations you can:
- Run the elastic-synthetics locations command with the deployment's Kibana URL.
- Go to Synthetics > Management and click Create monitor. Locations will be listed in Locations.
name string Required

The monitor name.
namespace string

The namespace field should be lowercase and not contain spaces. The namespace must not include any of the following characters: *, \, /, ?, ", <, >, |, whitespace, ,, #, :, or -.

Default value is default.
params string

The monitor parameters.
private_locations array[string]
The private locations to which the monitors will be deployed. These private locations refer to locations hosted and managed by you, whereas locations are hosted by Elastic. You can specify a private location using the location's name. To list available private locations you can:
- Run the elastic-synthetics locations command with the deployment's Kibana URL.
- Go to Synthetics > Settings and click Private locationsr. Private locations will be listed in the table.
You can provide locations or private_locations or both. At least one is required.
retest_on_failure boolean

Turn retesting for when a monitor fails on or off. By default, monitors are automatically retested if the monitor goes from "up" to "down". If the result of the retest is also "down", an error will be created and if configured, an alert sent. The monitor will then resume running according to the defined schedule. Using retest_on_failure can reduce noise related to transient problems.

Default value is true.
schedule number

The monitor's schedule in minutes. Supported values are 1, 3, 5, 10, 15, 30, 60, 120, and 240. The default value is 3 minutes for HTTP, TCP, and ICMP monitors. The default value is 10 minutes for Browser monitors.
service.name string

The APM service name.
tags array[string]

An array of tags.
timeout number

The monitor timeout in seconds. The monitor will fail if it doesn't complete within this time.

Default value is 16.
host string Required

The host to ping.
type string Required

The monitor type.

Value is icmp.
wait number

The wait time in seconds.

Default value is 1.

alert object

The alert configuration. The default is { status: { enabled: true }, tls: { enabled: true } }.
enabled boolean

Specify whether the monitor is enabled.

Default value is true.
labels object

Key-value pairs of labels to associate with the monitor. Labels can be used for filtering and grouping monitors.
Hide labels attribute Show labels attribute object
- * string Additional properties
locations array[string]
The location to deploy the monitor. Monitors can be deployed in multiple locations so that you can detect differences in availability and response times across those locations. To list available locations you can:
- Run the elastic-synthetics locations command with the deployment's Kibana URL.
- Go to Synthetics > Management and click Create monitor. Locations will be listed in Locations.
name string Required

The monitor name.
namespace string

The namespace field should be lowercase and not contain spaces. The namespace must not include any of the following characters: *, \, /, ?, ", <, >, |, whitespace, ,, #, :, or -.

Default value is default.
params string

The monitor parameters.
private_locations array[string]
The private locations to which the monitors will be deployed. These private locations refer to locations hosted and managed by you, whereas locations are hosted by Elastic. You can specify a private location using the location's name. To list available private locations you can:
- Run the elastic-synthetics locations command with the deployment's Kibana URL.
- Go to Synthetics > Settings and click Private locationsr. Private locations will be listed in the table.
You can provide locations or private_locations or both. At least one is required.
retest_on_failure boolean

Turn retesting for when a monitor fails on or off. By default, monitors are automatically retested if the monitor goes from "up" to "down". If the result of the retest is also "down", an error will be created and if configured, an alert sent. The monitor will then resume running according to the defined schedule. Using retest_on_failure can reduce noise related to transient problems.

Default value is true.
schedule number

The monitor's schedule in minutes. Supported values are 1, 3, 5, 10, 15, 30, 60, 120, and 240. The default value is 3 minutes for HTTP, TCP, and ICMP monitors. The default value is 10 minutes for Browser monitors.
service.name string

The APM service name.
tags array[string]

An array of tags.
timeout number

The monitor timeout in seconds. The monitor will fail if it doesn't complete within this time.

Default value is 16.
host string Required

The host to monitor; it can be an IP address or a hostname. The host can include the port using a colon, for example "example.com:9200".
proxy_url string

The URL of the SOCKS5 proxy to use when connecting to the server. The value must be a URL with a scheme of socks5://. If the SOCKS5 proxy server requires client authentication, then a username and password can be embedded in the URL. When using a proxy, hostnames are resolved on the proxy server instead of on the client. You can change this behavior by setting the proxy_use_local_resolver option.
proxy_use_local_resolver boolean

Specify that hostnames are resolved locally instead of being resolved on the proxy server. If false, name resolution occurs on the proxy server.

Default value is false.
ssl object

The TLS/SSL connection settings for use with the HTTPS endpoint. If you don't specify settings, the system defaults are used.
type string Required

The monitor type.

Value is tcp.

Responses

200

A successful response.

POST /api/synthetics/monitors

curl \
 --request POST 'https://localhost:5601/api/synthetics/monitors' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"type\": \"http\",\n  \"name\": \"Website Availability\",\n  \"url\": \"https://example.com\",\n  \"tags\": [\"website\", \"availability\"],\n  \"locations\": [\"united_kingdom\"]\n}"'

Request examples

Create an HTTP monitor to check a website's availability.

{
  "type": "http",
  "name": "Website Availability",
  "url": "https://example.com",
  "tags": ["website", "availability"],
  "locations": ["united_kingdom"]
}

Create a TCP monitor to monitor a server's availability.

{
  "type": "tcp",
  "name": "Server Availability",
  "host": "example.com",
  "private_locations": ["my_private_location"]
}

Create an ICMP monitor to perform ping checks.

{
  "type": "icmp",
  "name": "Ping Test",
  "host": "example.com",
  "locations": ["united_kingdom"]
}

Create a browser monitor to check a website.

{
  "type": "browser",
  "name": "Example journey",
  "inline_script": "step('Go to https://google.com.co', () => page.goto('https://www.google.com'))",
  "locations": ["united_kingdom"]
}