--- type: api title: Update a monitor description: **Spaces method and path for this operation:** url: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/kibana-serverless/operation/operation-put-synthetic-monitor resource: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/kibana-serverless/operation/operation-put-synthetic-monitor products: - Kibana --- # Update a monitor - Server: `https://{kibana_url}` ## Paths - `PUT` `/api/synthetics/monitors/{id}` - `PUT` `/s/{space_id}/api/synthetics/monitors/{id}` #### Path parameters - `id` (string · min length: 1 · max length: 1024) — required The identifier for the monitor that you want to update. ## Description Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-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 - Privileges: `uptime-read` and `uptime-write` ## Authentication - Api key: `Authorization: ` You must create an API key and use the encoded value in the request header. To learn about creating keys, go to [API keys](https://www.elastic.co/docs/current/serverless/api-keys). ## Header parameters - `kbn-xsrf` (string) — required A required header to protect against CSRF attacks ## Request body `application/json` - `alert` (map string to {} object) — optional The alert configuration. The default is `{ status: { enabled: true }, tls: { enabled: true } }`. - `status` (map string to {} object) — optional - `enabled` (boolean) — required - `groupBy` (string) — optional - `tls` (map string to {} object) — optional - `enabled` (boolean) — required - `groupBy` (string) — optional - `certificate_error_spki_allowlist` (object) — optional Any JSON value. - `check` (object) — optional Any JSON value. - `check.receive` (object) — optional Any JSON value. - `check.request.body` (object) — optional Any JSON value. - `check.request.headers` (object) — optional Any JSON value. - `check.request.method` (object) — optional Any JSON value. - `check.response.body.negative` (object) — optional Any JSON value. - `check.response.body.positive` (object) — optional Any JSON value. - `check.response.headers` (object) — optional Any JSON value. - `check.response.json` (object) — optional Any JSON value. - `check.response.status` (object) — optional Any JSON value. - `check.send` (object) — optional Any JSON value. - `enabled` (boolean) — optional Specify whether the monitor is enabled. Defaults to `true`. - `filter_journeys` (object) — optional Any JSON value. - `filter_journeys.match` (object) — optional Any JSON value. - `filter_journeys.tags` (object) — optional Any JSON value. - `host` (string · max length: 4096) — optional The host to monitor; it can be an IP address or a hostname. - `id` (object) — optional Any JSON value. - `ignore_https_errors` (object) — optional Any JSON value. - `inline_script` (string · max length: 1000000) — optional The inline script. - `ipv4` (boolean) — optional If `true`, ping using the ipv4 protocol. Defaults to `true`. - `ipv6` (boolean) — optional If `true`, ping using the ipv6 protocol. Defaults to `true`. - `kerberos` (object) — optional Any JSON value. - `labels` (map string to string) — optional Key-value pairs of labels to associate with the monitor. Labels can be used for filtering and grouping monitors. Map values (string · max length: 1000000) - `locations` (union anyOf[] · max items: 1000) — optional 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. - **string** - **Location object** - `id` (string · min length: 1 · max length: 1024) — required - `maintenance_windows` (string[] · max items: 1000) — optional The IDs of the maintenance windows to apply to the monitor. - `max_redirects` (union string | number) — optional The maximum number of redirects to follow. Defaults to `0`. - `mode` (enum) — optional 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) — optional The monitor name. - `namespace` (string) — optional 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) — optional Any JSON value. - `params` (union anyOf) — optional The monitor parameters, as a JSON string or an object. Any of: `string` or `Key-value object` - `password` (object) — optional Any JSON value. - `playwright_options` (object) — optional Any JSON value. - `playwright_text_assertion` (object) — optional Any JSON value. - `private_locations` (union anyOf[] · max items: 1000) — optional 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*. - **string** - **Location object** - `id` (string · min length: 1 · max length: 1024) — required - `proxy_headers` (object) — optional Any JSON value. - `proxy_url` (object) — optional Any JSON value. - `proxy_use_local_resolver` (object) — optional Any JSON value. - `response` (object) — optional Any JSON value. - `response.include_body` (object) — optional Any JSON value. - `response.include_body_max_bytes` (object) — optional Any JSON value. - `response.include_headers` (object) — optional Any JSON value. - `retest_on_failure` (boolean) — optional 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) — optional 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. - **number** - **Number and unit** - `number` (union string | number) — required - `unit` (enum) — required Values: `m`, `s` - `screenshots` (object) — optional Any JSON value. - `service.name` (object) — optional Any JSON value. - `source` (object) — optional Any JSON value. - `source.inline` (object) — optional Any JSON value. - `source.inline.script` (object) — optional Any JSON value. - `source.project.content` (object) — optional Any JSON value. - `spaces` (string[] · max items: 1000) — optional The IDs of additional spaces to make the monitor available in, besides the current space. - `ssl` (object) — optional Any JSON value. - `ssl.certificate` (object) — optional Any JSON value. - `ssl.certificate_authorities` (object) — optional Any JSON value. - `ssl.key` (object) — optional Any JSON value. - `ssl.key_passphrase` (object) — optional Any JSON value. - `ssl.supported_protocols` (object) — optional Any JSON value. - `ssl.verification_mode` (object) — optional Any JSON value. - `synthetics_args` (object) — optional Any JSON value. - `tags` (union string | string[]) — optional An array of tags. - `throttling` (object) — optional Any JSON value. - `timeout` (union string | number) — optional 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) — optional Values: `http`, `tcp`, `icmp`, `browser`, `api` - `url` (string · max length: 4096) — optional The URL to monitor. - `username` (object) — optional Any JSON value. - `wait` (object) — optional Any JSON value. ## Responses #### `200` A successful response. The response may include a `warnings` array when the monitor configuration has non-critical issues. `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. #### `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. ## Code examples #### Console ```console PUT kbn://api/synthetics/monitors/monitor-id {"type":"http","name":"Website Availability","url":"https://example.com","tags":["website","availability"],"locations":["united_kingdom"]} ``` #### curl ```curl 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"]}' ``` ## Response examples #### Response with warning A response when a browser monitor specifies a timeout but has no private locations. ```json { "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" ] } ] } ```