Update a monitor

Base URL: https://{kibana_url}

PUT /api/synthetics/monitors/{id}
PUT /s/{space_id}/api/synthetics/monitors/{id}

Auth

Update a monitor with the specified attributes. 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. You can also partially update a monitor. This will only update the fields that are specified in the request body. All other fields are left unchanged. The specified fields should conform to the monitor type. For example, you can't update the inline_scipt field of a HTTP monitor.

Path parameters

space_id string optional: An identifier for the space. If space_id is not provided in the URL, the default space is used. Refer to Spaces for more information.
id string required: The identifier for the monitor that you want to update.

Request body

One of:

type: browser

type enum required: The monitor type.; Values: browser
alert object: The alert configuration. The default is { status: { enabled: true }, tls: { enabled: true } }.
enabled boolean · default: true: Specify whether the monitor is enabled.
labels map string to string: Key-value pairs of labels to associate with the monitor. Labels can be used for filtering and grouping monitors.
locations 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.; External docs
name string required: The monitor name.
namespace string · default: default: The namespace field should be lowercase and not contain spaces. The namespace must not include any of the following characters: *, \, /, ?, ", <, >, |, whitespace, ,, #, :, or -.
params string: The monitor parameters.
private_locations 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.

Note

You can provide locations or private_locations or both. At least one is required.
retest_on_failure boolean · default: true: 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.
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 string[]: An array of tags.
timeout number · default: 16: The monitor timeout in seconds. The monitor will fail if it doesn't complete within this time.
ignore_https_errors boolean · default: false: Ignore HTTPS errors.
inline_script string required: The inline script.
playwright_options object: Playwright options.
screenshots enum · default: on: The screenshot option.; Values: on off only-on-failure
synthetics_args string[]: Synthetics agent CLI arguments.

type: http

type enum required: The monitor type.; Values: http
alert object: The alert configuration. The default is { status: { enabled: true }, tls: { enabled: true } }.
enabled boolean · default: true: Specify whether the monitor is enabled.
labels map string to string: Key-value pairs of labels to associate with the monitor. Labels can be used for filtering and grouping monitors.
locations 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.; External docs
name string required: The monitor name.
namespace string · default: default: The namespace field should be lowercase and not contain spaces. The namespace must not include any of the following characters: *, \, /, ?, ", <, >, |, whitespace, ,, #, :, or -.
params string: The monitor parameters.
private_locations 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.

Note

You can provide locations or private_locations or both. At least one is required.
retest_on_failure boolean · default: true: 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.
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 string[]: An array of tags.
timeout number · default: 16: The monitor timeout in seconds. The monitor will fail if it doesn't complete within this time.
check object: The check request settings.
ipv4 boolean · default: true: If true, ping using the ipv4 protocol.
ipv6 boolean · default: true: If true, ping using the ipv6 protocol.
max_redirects number · default: 0: The maximum number of redirects to follow.
mode enum · default: any: 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: all 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.
url string required: The URL to monitor.
username string: The username for authenticating with the server. The credentials are passed with the request.

type: icmp

type enum required: The monitor type.; Values: icmp
alert object: The alert configuration. The default is { status: { enabled: true }, tls: { enabled: true } }.
enabled boolean · default: true: Specify whether the monitor is enabled.
labels map string to string: Key-value pairs of labels to associate with the monitor. Labels can be used for filtering and grouping monitors.
locations 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.; External docs
name string required: The monitor name.
namespace string · default: default: The namespace field should be lowercase and not contain spaces. The namespace must not include any of the following characters: *, \, /, ?, ", <, >, |, whitespace, ,, #, :, or -.
params string: The monitor parameters.
private_locations 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.

Note

You can provide locations or private_locations or both. At least one is required.
retest_on_failure boolean · default: true: 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.
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 string[]: An array of tags.
timeout number · default: 16: The monitor timeout in seconds. The monitor will fail if it doesn't complete within this time.
host string required: The host to ping.
wait number · default: 1: The wait time in seconds.

type: tcp

type enum required: The monitor type.; Values: tcp
alert object: The alert configuration. The default is { status: { enabled: true }, tls: { enabled: true } }.
enabled boolean · default: true: Specify whether the monitor is enabled.
labels map string to string: Key-value pairs of labels to associate with the monitor. Labels can be used for filtering and grouping monitors.
locations 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.; External docs
name string required: The monitor name.
namespace string · default: default: The namespace field should be lowercase and not contain spaces. The namespace must not include any of the following characters: *, \, /, ?, ", <, >, |, whitespace, ,, #, :, or -.
params string: The monitor parameters.
private_locations 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.

Note

You can provide locations or private_locations or both. At least one is required.
retest_on_failure boolean · default: true: 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.
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 string[]: An array of tags.
timeout number · default: 16: The monitor timeout in seconds. The monitor will fail if it doesn't complete within this time.
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 · default: false: Specify that hostnames are resolved locally instead of being resolved on the proxy server. If false, name resolution occurs on the proxy server.
ssl object: The TLS/SSL connection settings for use with the HTTPS endpoint. If you don't specify settings, the system defaults are used.

Response

200