Update a monitor

Base URL: https://{kibana_url}

PUT /api/synthetics/monitors/{id}
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

Authentication

Path parameters

Header parameters

Request body

alert map string to {} object

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

certificate_error_spki_allowlist object

Any JSON value.

check object

Any JSON value.

check.receive object

Any JSON value.

check.request.body object

Any JSON value.

check.request.headers object

Any JSON value.

check.request.method object

Any JSON value.

check.response.body.negative object

Any JSON value.

check.response.body.positive object

Any JSON value.

check.response.headers object

Any JSON value.

check.response.json object

Any JSON value.

check.response.status object

Any JSON value.

check.send object

Any JSON value.

enabled boolean

Specify whether the monitor is enabled. Defaults to true.

filter_journeys object

Any JSON value.

filter_journeys.match object

Any JSON value.

filter_journeys.tags object

Any JSON value.

host string · max length: 4096

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

id object

Any JSON value.

ignore_https_errors object

Any JSON value.

inline_script string · max length: 1000000

The inline script.

ipv4 boolean

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

ipv6 boolean

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

kerberos object

Any JSON value.

labels map string to string

Key-value pairs of labels to associate with the monitor. Labels can be used for filtering and grouping monitors.

<string> string · max length: 1000000

locations union anyOf[] · max items: 1000

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.

Any of:

string

maintenance_windows string[] · max items: 1000

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

max_redirects union string | number

The maximum number of redirects to follow. Defaults to 0.

mode enum

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: any all

name string · max length: 4096

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 -. Defaults to default.

ntlm object

Any JSON value.

params union anyOf

The monitor parameters, as a JSON string or an object.

Any of: string or Key-value object

password object

Any JSON value.

playwright_options object

Any JSON value.

playwright_text_assertion object

Any JSON value.

private_locations union anyOf[] · max items: 1000

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.

Any of:

string

proxy_headers object

Any JSON value.

proxy_url object

Any JSON value.

proxy_use_local_resolver object

Any JSON value.

response object

Any JSON value.

response.include_body object

Any JSON value.

response.include_body_max_bytes object

Any JSON value.

response.include_headers object

Any JSON value.

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 union anyOf

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:

number

screenshots object

Any JSON value.

service.name object

Any JSON value.

source object

Any JSON value.

source.inline object

Any JSON value.

source.inline.script object

Any JSON value.

source.project.content object

Any JSON value.

spaces string[] · max items: 1000

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

ssl object

Any JSON value.

ssl.certificate object

Any JSON value.

ssl.certificate_authorities object

Any JSON value.

ssl.key object

Any JSON value.

ssl.key_passphrase object

Any JSON value.

ssl.supported_protocols object

Any JSON value.

ssl.verification_mode object

Any JSON value.

synthetics_args object

Any JSON value.

tags union string | string[]

An array of tags.

throttling object

Any JSON value.

timeout union string | 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.

type enum

Values: http tcp icmp browser api

url string · max length: 4096

The URL to monitor.

username object

Any JSON value.

wait object

Any JSON value.

Responses

A successful response. The response may include a warnings array when the monitor configuration has non-critical issues.

application/json

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.

Base URL: https://{kibana_url}

Examples

Request Console 1 / 2 languages

Console Kibana Dev Tools

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

curl Shell

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"]}'

Request Console 1 / 2 languages

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

Console Kibana Dev Tools

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

Generated from the API spec

curl Shell

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

Generated from the API spec

Response

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 \u0022Example journey\u0022 specifies a timeout and is running on public locations: \u0022public-1, public-2\u0022. The timeout will have no effect on these locations.",
      "publicLocationIds": [
        "public-1",
        "public-2"
      ]
    }
  ]
}

Request Console 1 / 2 languages

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

Console Kibana Dev Tools

PUT kbn:/api/synthetics/monitors/ID
{
  "host": "example.com",
  "name": "Server Availability",
  "private_locations": [
    "my_private_location"
  ],
  "type": "tcp"
}

Generated from the API spec

curl Shell

curl \
  -X PUT "${KIBANA_URL}/api/synthetics/monitors/${ID}" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "example.com",
    "name": "Server Availability",
    "private_locations": [
      "my_private_location"
    ],
    "type": "tcp"
  }'

Generated from the API spec

Response

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 \u0022Example journey\u0022 specifies a timeout and is running on public locations: \u0022public-1, public-2\u0022. The timeout will have no effect on these locations.",
      "publicLocationIds": [
        "public-1",
        "public-2"
      ]
    }
  ]
}

Request Console 1 / 2 languages

Update an ICMP monitor that performs ping checks.

Console Kibana Dev Tools

PUT kbn:/api/synthetics/monitors/ID
{
  "host": "example.com",
  "locations": [
    "united_kingdom"
  ],
  "name": "Ping Test",
  "type": "icmp"
}

Generated from the API spec

curl Shell

curl \
  -X PUT "${KIBANA_URL}/api/synthetics/monitors/${ID}" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "example.com",
    "locations": [
      "united_kingdom"
    ],
    "name": "Ping Test",
    "type": "icmp"
  }'

Generated from the API spec

Response

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 \u0022Example journey\u0022 specifies a timeout and is running on public locations: \u0022public-1, public-2\u0022. The timeout will have no effect on these locations.",
      "publicLocationIds": [
        "public-1",
        "public-2"
      ]
    }
  ]
}

Request Console 1 / 2 languages

Update a browser monitor that checks a website.

Console Kibana Dev Tools

PUT kbn:/api/synthetics/monitors/ID
{
  "inline_script": "step(\u0027Go to https://google.com.co\u0027, () =\u003E page.goto(\u0027https://www.google.com\u0027))",
  "locations": [
    "united_kingdom"
  ],
  "name": "Example journey",
  "type": "browser"
}

Generated from the API spec

curl Shell

curl \
  -X PUT "${KIBANA_URL}/api/synthetics/monitors/${ID}" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "inline_script": "step(\u0027Go to https://google.com.co\u0027, () =\u003E page.goto(\u0027https://www.google.com\u0027))",
    "locations": [
      "united_kingdom"
    ],
    "name": "Example journey",
    "type": "browser"
  }'

Generated from the API spec

Response

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 \u0022Example journey\u0022 specifies a timeout and is running on public locations: \u0022public-1, public-2\u0022. The timeout will have no effect on these locations.",
      "publicLocationIds": [
        "public-1",
        "public-2"
      ]
    }
  ]
}

Request Console 1 / 2 languages

Disable a monitor without changing any other field.

Console Kibana Dev Tools

PUT kbn:/api/synthetics/monitors/ID
{
  "enabled": false
}

Generated from the API spec

curl Shell

curl \
  -X PUT "${KIBANA_URL}/api/synthetics/monitors/${ID}" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Generated from the API spec

Response

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 \u0022Example journey\u0022 specifies a timeout and is running on public locations: \u0022public-1, public-2\u0022. The timeout will have no effect on these locations.",
      "publicLocationIds": [
        "public-1",
        "public-2"
      ]
    }
  ]
}

Required authorization

Authentication

Path parameters

Header parameters

Request body { }

Responses

Request body