Create a monitor

Base URL
https://{kibana_url}
  • POST /api/synthetics/monitors
  • POST /s/{space_id}/api/synthetics/monitors
Auth

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.

Required authorization

Privileges uptime-read and uptime-write

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.

Query parameters

id string · max length: 1024

A custom ID for the new monitor. Generated if omitted.

preserve_namespace union enum | boolean

If true, store the namespace as sent. Otherwise, a default namespace is replaced with one derived from the space ID.

Values: true false

Header parameters

kbn-xsrf string required

A required header to protect against CSRF attacks

Request body

One of:
type: http
type enum required

The monitor type.

Values: http
alert map string to {} object

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

status map string to {} object
enabled boolean required
groupBy string
tls map string to {} object
enabled boolean required
groupBy string
check 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.

enabled boolean

Specify whether the monitor is enabled. Defaults to true.

id object

Any JSON value.

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:
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.

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:
proxy_headers object

Any JSON value.

proxy_url 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:
service.name 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.

tags union string | string[]

An array of tags.

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.

url string · max length: 4096

The URL to monitor.

username object

Any JSON value.

Responses

A successful response. The response may include a warnings array when the monitor configuration has non-critical issues. For example, if a browser monitor specifies a timeout but has no private locations configured, a warning is returned indicating the timeout will have no effect.

application/json
warnings object[]

An optional array of warnings about the monitor configuration.

message string

A human-readable warning message.

monitorId string

The monitor ID associated with the warning.

publicLocationIds string[]

The public location IDs associated with the warning.

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

application/json
attributes object
details string
error string
message string
statusCode integer
Base URL
https://{kibana_url}