Create a monitor
https://{kibana_url}
- POST /api/synthetics/monitors
- POST /s/{space_id}/api/synthetics/monitors
Refer to Spaces for more information.
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.
Request
type: browser
-
alertobject -
The alert configuration. The default is
{ status: { enabled: true }, tls: { enabled: true } }. -
enabledboolean · default: true -
Specify whether the monitor is enabled.
-
labelsmap string to string -
Key-value pairs of labels to associate with the monitor. Labels can be used for filtering and grouping monitors.
-
locationsstring -
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 locationscommand with the deployment's Kibana URL. - Go to Synthetics > Management and click Create monitor. Locations will be listed in Locations.
- Run the
- External docs
-
namestringrequired -
The monitor name.
-
namespacestring · default: default -
The namespace field should be lowercase and not contain spaces. The namespace must not include any of the following characters:
*,\,/,?,",<,>,|, whitespace,,,#,:, or-. -
paramsstring -
The monitor parameters.
-
private_locationsstring -
The private locations to which the monitors will be deployed. These private locations refer to locations hosted and managed by you, whereas
locationsare 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 locationscommand with the deployment's Kibana URL. - Go to Synthetics > Settings and click Private locationsr. Private locations will be listed in the table.
info You can provide
locationsorprivate_locationsor both. At least one is required. - Run the
-
retest_on_failureboolean · 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_failurecan reduce noise related to transient problems. -
schedulenumber -
The monitor's schedule in minutes. Supported values are
1,3,5,10,15,30,60,120, and240. The default value is3minutes for HTTP, TCP, and ICMP monitors. The default value is10minutes for Browser monitors. -
service.namestring -
The APM service name.
-
An array of tags.
-
timeoutnumber · default: 16 -
The monitor timeout in seconds. The monitor will fail if it doesn't complete within this time.
-
ignore_https_errorsboolean · default: false -
Ignore HTTPS errors.
-
inline_scriptstringrequired -
The inline script.
-
playwright_optionsobject -
Playwright options.
-
synthetics_argsstring -
Synthetics agent CLI arguments.
type: http
-
alertobject -
The alert configuration. The default is
{ status: { enabled: true }, tls: { enabled: true } }. -
enabledboolean · default: true -
Specify whether the monitor is enabled.
-
labelsmap string to string -
Key-value pairs of labels to associate with the monitor. Labels can be used for filtering and grouping monitors.
-
locationsstring -
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 locationscommand with the deployment's Kibana URL. - Go to Synthetics > Management and click Create monitor. Locations will be listed in Locations.
- Run the
- External docs
-
namestringrequired -
The monitor name.
-
namespacestring · default: default -
The namespace field should be lowercase and not contain spaces. The namespace must not include any of the following characters:
*,\,/,?,",<,>,|, whitespace,,,#,:, or-. -
paramsstring -
The monitor parameters.
-
private_locationsstring -
The private locations to which the monitors will be deployed. These private locations refer to locations hosted and managed by you, whereas
locationsare 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 locationscommand with the deployment's Kibana URL. - Go to Synthetics > Settings and click Private locationsr. Private locations will be listed in the table.
info You can provide
locationsorprivate_locationsor both. At least one is required. - Run the
-
retest_on_failureboolean · 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_failurecan reduce noise related to transient problems. -
schedulenumber -
The monitor's schedule in minutes. Supported values are
1,3,5,10,15,30,60,120, and240. The default value is3minutes for HTTP, TCP, and ICMP monitors. The default value is10minutes for Browser monitors. -
service.namestring -
The APM service name.
-
An array of tags.
-
timeoutnumber · default: 16 -
The monitor timeout in seconds. The monitor will fail if it doesn't complete within this time.
-
checkobject -
The check request settings.
-
requestobject -
An optional request to send to the remote host.
-
ipv4boolean · default: true -
If
true, ping using the ipv4 protocol. -
ipv6boolean · default: true -
If
true, ping using the ipv6 protocol. -
max_redirectsnumber · default: 0 -
The maximum number of redirects to follow.
-
mode· default: any -
The mode of the monitor. If it is
all, the monitor pings all resolvable IPs for a hostname. If it isany, 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 useall. -
Values:
allany -
passwordstring -
The password for authenticating with the server. The credentials are passed with the request.
-
proxy_headersobject -
Additional headers to send to proxies during CONNECT requests.
-
proxy_urlstring -
The URL of the proxy to use for this monitor.
-
responseobject -
Controls the indexing of the HTTP response body contents to the
http.response.body.contents field. -
sslobject -
The TLS/SSL connection settings for use with the HTTPS endpoint. If you don't specify settings, the system defaults are used.
-
urlstringrequired -
The URL to monitor.
-
usernamestring -
The username for authenticating with the server. The credentials are passed with the request.
type: icmp
-
alertobject -
The alert configuration. The default is
{ status: { enabled: true }, tls: { enabled: true } }. -
enabledboolean · default: true -
Specify whether the monitor is enabled.
-
labelsmap string to string -
Key-value pairs of labels to associate with the monitor. Labels can be used for filtering and grouping monitors.
-
locationsstring -
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 locationscommand with the deployment's Kibana URL. - Go to Synthetics > Management and click Create monitor. Locations will be listed in Locations.
- Run the
- External docs
-
namestringrequired -
The monitor name.
-
namespacestring · default: default -
The namespace field should be lowercase and not contain spaces. The namespace must not include any of the following characters:
*,\,/,?,",<,>,|, whitespace,,,#,:, or-. -
paramsstring -
The monitor parameters.
-
private_locationsstring -
The private locations to which the monitors will be deployed. These private locations refer to locations hosted and managed by you, whereas
locationsare 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 locationscommand with the deployment's Kibana URL. - Go to Synthetics > Settings and click Private locationsr. Private locations will be listed in the table.
info You can provide
locationsorprivate_locationsor both. At least one is required. - Run the
-
retest_on_failureboolean · 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_failurecan reduce noise related to transient problems. -
schedulenumber -
The monitor's schedule in minutes. Supported values are
1,3,5,10,15,30,60,120, and240. The default value is3minutes for HTTP, TCP, and ICMP monitors. The default value is10minutes for Browser monitors. -
service.namestring -
The APM service name.
-
An array of tags.
-
timeoutnumber · default: 16 -
The monitor timeout in seconds. The monitor will fail if it doesn't complete within this time.
-
hoststringrequired -
The host to ping.
-
waitnumber · default: 1 -
The wait time in seconds.
type: tcp
-
alertobject -
The alert configuration. The default is
{ status: { enabled: true }, tls: { enabled: true } }. -
enabledboolean · default: true -
Specify whether the monitor is enabled.
-
labelsmap string to string -
Key-value pairs of labels to associate with the monitor. Labels can be used for filtering and grouping monitors.
-
locationsstring -
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 locationscommand with the deployment's Kibana URL. - Go to Synthetics > Management and click Create monitor. Locations will be listed in Locations.
- Run the
- External docs
-
namestringrequired -
The monitor name.
-
namespacestring · default: default -
The namespace field should be lowercase and not contain spaces. The namespace must not include any of the following characters:
*,\,/,?,",<,>,|, whitespace,,,#,:, or-. -
paramsstring -
The monitor parameters.
-
private_locationsstring -
The private locations to which the monitors will be deployed. These private locations refer to locations hosted and managed by you, whereas
locationsare 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 locationscommand with the deployment's Kibana URL. - Go to Synthetics > Settings and click Private locationsr. Private locations will be listed in the table.
info You can provide
locationsorprivate_locationsor both. At least one is required. - Run the
-
retest_on_failureboolean · 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_failurecan reduce noise related to transient problems. -
schedulenumber -
The monitor's schedule in minutes. Supported values are
1,3,5,10,15,30,60,120, and240. The default value is3minutes for HTTP, TCP, and ICMP monitors. The default value is10minutes for Browser monitors. -
service.namestring -
The APM service name.
-
An array of tags.
-
timeoutnumber · default: 16 -
The monitor timeout in seconds. The monitor will fail if it doesn't complete within this time.
-
hoststringrequired -
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_urlstring -
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 theproxy_use_local_resolveroption. -
proxy_use_local_resolverboolean · 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. -
sslobject -
The TLS/SSL connection settings for use with the HTTPS endpoint. If you don't specify settings, the system defaults are used.
Response
A successful response.