Update a monitor

PUT /api/synthetics/monitors/{id}

Spaces method and path for this operation:

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

Refer to Spaces for more information.

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_script field of a HTTP monitor.

[Required authorization] Route required privileges: uptime-read AND uptime-write.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

The identifier for the monitor that you want to update.

Minimum length is 1, maximum length is 1024.

application/json

Body

alert object

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

Additional properties are allowed.
Hide alert attributes Show alert attributes object
- status object
  
  Additional properties are allowed.
  Hide status attributes Show status attributes object
  
  enabled boolean Required
  
  groupBy string
- tls object
  
  Additional properties are allowed.
  Hide tls attributes Show tls attributes object
  
  enabled boolean Required
  
  groupBy string
certificate_error_spki_allowlist

PEM certificates whose public keys (SPKI) are allowlisted so Chromium bypasses certificate errors for matching presented certificates. This does not add a CA to Chromium's trust store.
check

The check request settings, as nested request and response objects.
check.request.body

Optional request body content.
check.request.headers

A dictionary of additional HTTP headers to send. By default, Synthetics sets the User-Agent header to identify itself.
check.request.method

The HTTP method to use: HEAD, GET, POST, or OPTIONS.
check.response.headers

A dictionary of expected HTTP headers. If the header is not found, the check fails.
enabled boolean

Specify whether the monitor is enabled. Defaults to true.
host string

The host to monitor; it can be an IP address or a hostname.

Maximum length is 4096.
ignore_https_errors

Ignore HTTPS errors. Defaults to false.
inline_script string

The inline script.

Maximum length is 1000000.
ipv4 boolean

If true, ping using the ipv4 protocol. Defaults to true.
ipv6 boolean

If true, ping using the ipv6 protocol. Defaults to 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
  
  Maximum length is 1000000.
locations array[string | object]

The Elastic-managed locations to deploy the monitor to. 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, run the elastic-synthetics locations command with the deployment's Kibana URL, or go to Synthetics > Management and click Create monitor.

You can provide locations or private_locations or both. At least one is required.

Not more than 1000 elements.
Any of:
Location ID string Location object object

Minimum length is 1, maximum length is 1024.
Hide attribute Show attribute

id string Required

Minimum length is 1, maximum length is 1024.
maintenance_windows array[string]

The IDs of the maintenance windows to apply to the monitor.

Not more than 1000 elements. Maximum length of each is 1024.
max_redirects string | number
The maximum number of redirects to follow. Defaults to 0.

Any of:
Count as string string Count number

Maximum length is 32.
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, use all. Defaults to any.

Values are any or all.
name string

The monitor name.

Maximum length is 4096.
namespace string

The namespace field should be lowercase and not contain spaces. The namespace must not include any of the following characters: *, \, /, ?, ", <, >, |, whitespace, ,, #, :, or -. Defaults to default.
params string | object
The monitor parameters, as a JSON string or an object.
Any of:
JSON string string Key-value object object

Maximum length is 1000000.
Hide attribute Show attribute

* string Additional properties

Maximum length is 1000000.
password

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

Playwright options.
private_locations array[string | object]

The private locations to deploy the monitor to. These locations are 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, run the elastic-synthetics locations command with the deployment's Kibana URL, or go to Synthetics > Settings and click Private locations.

Not more than 1000 elements.
Any of:
Location ID string Location object object

Minimum length is 1, maximum length is 1024.
Hide attribute Show attribute

id string Required

Minimum length is 1, maximum length is 1024.
proxy_headers

Additional headers to send to proxies during CONNECT requests.
proxy_url

The URL of the proxy to use for this monitor.
proxy_use_local_resolver

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

Controls the indexing of the HTTP response body contents to the http.response.body.contents field.
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 is created and, if configured, an alert is sent. Using retest_on_failure can reduce noise related to transient problems.
schedule number | object
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, and 10 minutes for browser monitors.
Any of:
Minutes number Number and unit object
Hide attributes Show attributes

number string | number Required

Any of:
string-1 string number-2 number

Maximum length is 32.

unit string Required

Values are m or s.
screenshots

The screenshot option: on, off, or only-on-failure. Defaults to on.
service.name

The APM service name.
spaces array[string]

The IDs of additional spaces to make the monitor available in, besides the current space.

Not more than 1000 elements. Maximum length of each is 1024.
ssl

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

Synthetics agent CLI arguments.
tags string | array[string]
An array of tags.

Any of:
Single value string Multiple values array[string]

Maximum length is 4096.

Not more than 1000 elements. Maximum length of each is 4096.
timeout string | null | number
The monitor timeout in seconds. The monitor fails if it doesn't complete within this time. Defaults to 16.

For browser monitors, the minimum timeout is 30 seconds. Browser monitor timeouts only apply on private locations; on public locations the timeout has no effect and the response includes a warning.

Any of:
Seconds as string string | null Seconds number | null

Maximum length is 32.
type string

Values are http, tcp, icmp, browser, or api.
url string

The URL to monitor.

Maximum length is 4096.
username

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

The wait time in seconds. Defaults to 1.

Responses

200 application/json

A successful response. The response may include a warnings array when the monitor configuration has non-critical issues.
Hide response attribute Show response attribute object
- warnings array[object]
  
  An optional array of warnings about the monitor configuration.
  
  Hide warnings attributes Show warnings attributes object
  
  message string
  
  A human-readable warning message.
  
  monitorId string
  
  The monitor ID associated with the warning.
  
  publicLocationIds array[string]
  
  The public location IDs associated with the warning.
400

Bad request. For browser monitors, a 400 error is returned if the timeout is less than 30 seconds.
404

The monitor does not exist.

PUT /api/synthetics/monitors/{id}

curl \
  -X PUT "${KIBANA_URL}/api/synthetics/monitors/monitor-id" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{"type":"http","name":"Website Availability","url":"https://example.com","tags":["website","availability"],"locations":["united_kingdom"]}'

PUT kbn://api/synthetics/monitors/monitor-id
{"type":"http","name":"Website Availability","url":"https://example.com","tags":["website","availability"],"locations":["united_kingdom"]}

Request examples

Update an HTTP monitor that checks a website's availability.

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

Update a TCP monitor that monitors a server's availability.

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

Update an ICMP monitor that performs ping checks.

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

Update a browser monitor that checks a website.

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

Disable a monitor without changing any other field.

{
  "enabled": false
}

Response examples (200)

A response when a browser monitor specifies a timeout but has no private locations.

{
  "enabled": true,
  "name": "Example journey",
  "type": "browser",
  "warnings": [
    {
      "id": "monitor-id",
      "message": "For browser monitors, timeout is only supported on private locations. Browser monitor \"Example journey\" specifies a timeout and is running on public locations: \"public-1, public-2\". The timeout will have no effect on these locations.",
      "publicLocationIds": [
        "public-1",
        "public-2"
      ]
    }
  ]
}