Version: 6.1

Maintenance Windows API

Description

Maintenance mode temporarily excludes selected global metric dimensions from incident analysis and subsequent service health calculations.

Use this feature during scheduled and unscheduled maintenance activities, such as:

data migration
infrastructure upgrades
service restarts
server maintenance
network equipment upgrades
routine maintenance

During these operations, some metrics may temporarily enter a degraded state even though no actual failure has occurred. Maintenance mode prevents false positives and suppresses incidents caused by expected state changes.

During maintenance:

raw metric values continue to be calculated
state history remains unchanged
matching dimensions are marked with is_in_maintenance = true
these dimensions are excluded from service metric and service health calculations

Maintenance Window States

A maintenance window can have one of the following states:

State	Description
`planned`	The window has been created and is waiting for its scheduled start time (`start_at`)
`active`	Maintenance is active and applies to matching dimensions
`completed`	Maintenance ended automatically at `end_at` or was completed manually by a user
`cancelled`	The maintenance window was cancelled before its start time

CRUD Operations

Creating a Maintenance Window

Creates a maintenance window for one or more global metrics.

Request

Request example

POST _core/rsm/maintenance
{
  "name": "Scheduled maintenance for the Orders API",
  "groups": [
    {
      "name": "group-1",
      "elements": [
        {
          "name": "environment",
          "values": [
            "production"
          ]
        },
        {
          "name": "region",
          "values": [
            "ru-central"
          ]
        },
        {
          "name": "host_name",
          "values": [
            "app-node-*"
          ]
        },
        {
          "name": "order_operation",
          "values": []
        }
      ]
    }
  ],
  "metric_ids": [
    "7W6VHZ8BjUVSVN0e2bVN",
    "KW-lHZ8BjUVSVN0e7Bkc"
  ],
  "start_at": "2026-04-16T17:05:00.000Z",
  "end_at": "2026-04-16T19:50:00.000Z"
}

Request Parameters

Field	Type	Required	Description
`name`	string	Yes	Maintenance window name. Must not be empty
`groups`	array	Yes	Filter groups that define the scope. At least one group must be specified
`groups[].name`	string	Yes	Filter group name. Must not be empty
`groups[].elements`	array	Yes	Conditions within the group. At least one condition must be specified
`groups[].elements[].name`	string	Yes	Dimension name. Must not be empty
`groups[].elements[].values`	array[string]	Yes	Dimension values. An empty array selects all values of the dimension
`metric_ids`	array[string]	Yes	List of global metrics. At least one metric must be selected
`start_at`	datetime	Yes	Maintenance start time. Must be later than the current time
`end_at`	datetime	Yes	Maintenance end time. Must be later than the current time and later than `start_at`

Filter Logic

A metric dimension is placed in maintenance if it fully matches at least one filter group. To match a group, it must satisfy all conditions in that group.

If groups[].elements[].values is empty, the filter covers all values of the specified dimension.

Dimension values support wildcard patterns. A single filter value can therefore cover multiple dimension values that match the specified pattern.

Updating a Maintenance Window

Updates an existing maintenance window.

Request

Update request example

PUT _core/rsm/maintenance/{id}
{
  "name": "Scheduled maintenance for the Orders API",
  "groups": [
    {
      "name": "group-1",
      "elements": [
        {
          "name": "environment",
          "values": [
            "production"
          ]
        },
        {
          "name": "region",
          "values": [
            "ru-central"
          ]
        },
        {
          "name": "host_name",
          "values": [
            "app-node-01",
            "app-node-02"
          ]
        },
        {
          "name": "order_operation",
          "values": []
        }
      ]
    }
  ],
  "metric_ids": [
    "7W6VHZ8BjUVSVN0e2bVN",
    "KW-lHZ8BjUVSVN0e7Bkc"
  ],
  "start_at": "2026-04-16T17:05:00.000Z",
  "end_at": "2026-04-16T19:50:00.000Z"
}

Request Parameters

Use the same fields as when creating a maintenance window. The request also supports the state field, which is used to cancel a planned window.

Field	Type	Required	Description
`state`	string	No	New window state. The `cancelled` value cancels a planned window

The editing rules depend on the current window state:

State	Changing `start_at`	Changing `end_at`
`planned`	Allowed. The new value must be later than the current time	Allowed. The new value must be later than the current time and later than `start_at`
`active`	Not allowed	Allowed only if the new value is later than the current time
`completed`	Not allowed	Not allowed
`cancelled`	Not allowed	Not allowed

Windows in the completed and cancelled states cannot be edited.

Cancelling a Maintenance Window

Use the update request to cancel a window. Only a window in the planned state can be cancelled.

Request

PUT _core/rsm/maintenance/{id}
{
  "state": "cancelled"
}

After the request completes, the window enters the cancelled state and does not become active at the scheduled time.

Completing a Maintenance Window Manually

Completes an active maintenance window immediately. After the request completes, the window enters the completed state, and end_at is set to the date and time when the request was processed.

Request

POST _core/rsm/maintenance/{id}/completed

Getting the Maintenance Window List

Returns all created maintenance windows.

Request

GET _core/rsm/maintenance

The response contains an array of maintenance windows.

Getting a Maintenance Window

Returns information about a specific maintenance window.

Request

GET _core/rsm/maintenance/{id}

Response Example

Maintenance window

{
  "_meta": {
    "id": "0aFWcJ8Ba6VDXX_eQ4PI",
    "created": "2026-07-17T13:48:49.483Z",
    "updated": "2026-07-17T13:52:00.004Z",
    "type": "user",
    "tag_ids": [],
    "from_system": false
  },
  "_permissions": {
    "read": {
      "roles": [],
      "users": []
    },
    "write": {
      "roles": [],
      "users": []
    },
    "owner": "admin",
    "isWritable": true
  },
  "name": "Scheduled maintenance for the Orders API",
  "start_at": "2026-07-17T13:49:00.000Z",
  "end_at": "2026-07-17T13:52:00.000Z",
  "groups": [
    {
      "name": "group-1",
      "elements": [
        {
          "name": "environment",
          "values": [
            "production"
          ]
        },
        {
          "name": "region",
          "values": [
            "ru-central"
          ]
        },
        {
          "name": "host_name",
          "values": [
            "app-node-*"
          ]
        },
        {
          "name": "order_operation",
          "values": []
        }
      ]
    }
  ],
  "metrics": [
    {
      "id": "7W6VHZ8BjUVSVN0e2bVN",
      "name": "[prod] Orders API response time",
      "dimension_count": 4
    },
    {
      "id": "KW-lHZ8BjUVSVN0e7Bkc",
      "name": "[prod] Orders API error rate",
      "dimension_count": 4
    }
  ],
  "state": "completed"
}

Main Response Fields

Field	Description
`_meta.id`	Maintenance window ID
`_meta.created`	Creation date and time
`_meta.updated`	Date and time of the latest update
`_permissions.owner`	Maintenance window owner
`_permissions.isWritable`	Indicates whether the window can be edited
`name`	Maintenance window name
`start_at`	Maintenance start time
`end_at`	Maintenance end time
`groups`	Scope filter groups
`groups[].name`	Filter group name
`groups[].elements`	Conditions within the group
`groups[].elements[].name`	Dimension name
`groups[].elements[].values`	Dimension values
`metrics`	List of associated global metrics
`metrics[].id`	Global metric ID
`metrics[].name`	Global metric name
`metrics[].dimension_count`	Number of metric dimensions
`state`	Current maintenance window state

Deleting a Maintenance Window

Deletes a maintenance window in the planned or cancelled state.

Windows in the active and completed states cannot be deleted because they have already affected health calculations and are retained in the system as maintenance records.

Request

DELETE _core/rsm/maintenance/{id}

Display and Preview Requests

Checking Metric Coverage

Use this request to preview the scope before saving a maintenance window.

It allows you to:

determine the intersection of dimensions in the selected metrics
get a list of metric series that match the filter conditions
verify that the filter matches any metric series
show the user a preview of the maintenance mode scope

Coverage Check Request

Request

Request example

POST _core/rsm/maintenance/intersection
{
  "groups": [
    {
      "name": "group-1",
      "elements": [
        {
          "name": "host_name",
          "values": [
            "app-node-01",
            "app-node-02"
          ]
        }
      ]
    }
  ],
  "metric_ids": [
    "7W6VHZ8BjUVSVN0e2bVN",
    "KW-lHZ8BjUVSVN0e7Bkc"
  ]
}

Request Parameters

Field	Type	Required	Description
`groups`	array	Yes	Filter groups used to check coverage. At least one group must be specified
`metric_ids`	array[string]	Yes	Selected global metrics. At least one metric must be selected

Response Example

Intersection result

{
  "fields": [
    "environment",
    "region",
    "host_name",
    "order_operation"
  ],
  "metric_entities": [
    {
      "title": "[prod] Orders API response time",
      "dimensions": {
        "environment": "production",
        "region": "ru-central",
        "host_name": "app-node-01",
        "order_operation": "create_order"
      }
    },
    {
      "title": "[prod] Orders API response time",
      "dimensions": {
        "environment": "production",
        "region": "ru-central",
        "host_name": "app-node-01",
        "order_operation": "update_order"
      }
    },
    {
      "title": "[prod] Orders API error rate",
      "dimensions": {
        "environment": "production",
        "region": "ru-central",
        "host_name": "app-node-02",
        "order_operation": "get_order"
      }
    },
    {
      "title": "[prod] Orders API error rate",
      "dimensions": {
        "environment": "production",
        "region": "ru-central",
        "host_name": "app-node-02",
        "order_operation": "cancel_order"
      }
    }
  ]
}

Main Response Fields

Field	Description
`fields`	List of common dimensions: the intersection of dimensions in the selected global metrics
`metric_entities`	List of metric series that match the scope conditions
`metric_entities[].title`	Global metric name
`metric_entities[].dimensions`	Dimension values of the matching metric series

Getting Metrics by Dimensions

Returns global metrics that contain all specified dimensions.

Request

POST _core/rsm/parent_metrics/dimensions
{
  "dimensions": [
    "environment",
    "region",
    "host_name",
    "order_operation"
  ]
}

The response contains metrics that include all four dimensions: environment, region, host_name, and order_operation.

Getting Filter Value Suggestions

Returns values of the selected dimension for use in a maintenance window filter.

Request

POST _core/rsm/parent_metrics/filter_values
{
  "metric_ids": [],
  "filter": "region",
  "value": "*",
  "size": 50
}

Pass the IDs of the metrics whose dimension values must be combined in metric_ids. An empty array searches across all metrics. The filter field contains the dimension name, value contains the search pattern for its values, and size limits the number of suggestions in the response. The * value returns values without additional filtering.

Pass the text entered in the filter in value to receive matching suggestions as the user types. The user can also specify an arbitrary value that is not included in the suggestions.

Response Example

{
  "values": [
    "ru-central",
    "ru-northwest",
    "kz-central",
    "by-central"
  ]
}

Getting Global Metric Entities

Returns the entities of a global metric together with their dimensions, current health state, value history, and associated layers and services. The include_linked_info=true parameter adds maintenance mode information.

Request

GET _core/rsm/parent_metrics/7W6VHZ8BjUVSVN0e2bVN/entities?include_linked_info=true

Response Example

Global metric entities

[
  {
    "metric_id": "7W6VHZ8BjUVSVN0e2bVN",
    "entity_id": "12b9e3f4ce87853e44cfbaeb546bda55a8033d71d04504c6d9d57059b9c222bf",
    "entity_title": "environment: production; region: ru-central; host_name: app-node-01; order_operation: create_order",
    "dimensions": {
      "environment": "production",
      "region": "ru-central",
      "host_name": "app-node-01",
      "order_operation": "create_order"
    },
    "layers": [
      {
        "id": "hnDTHZ8BjUVSVN0eRyfS",
        "title": "Orders API infrastructure"
      }
    ],
    "services": [
      {
        "id": "K3DUHZ8BjUVSVN0eAi22",
        "title": "Order processing service"
      }
    ],
    "value": 3,
    "health_score": 25,
    "severity": "HIGH",
    "trend": [
      {
        "@timestamp": "2026-07-17T13:45:00.000Z",
        "value": null
      },
      {
        "@timestamp": "2026-07-17T13:50:00.000Z",
        "value": 3
      }
    ],
    "is_in_maintenance": true,
    "maintenances": [
      {
        "_meta": {
          "id": "0aFWcJ8Ba6VDXX_eQ4PI",
          "tag_ids": [],
          "created": "2026-07-17T13:48:49.483Z",
          "updated": "2026-07-17T13:52:00.004Z",
          "type": "user",
          "from_system": false
        },
        "name": "Scheduled maintenance for the Orders API",
        "start_at": "2026-07-17T13:49:00.000Z",
        "end_at": "2026-07-17T13:52:00.000Z"
      }
    ]
  }
]

The is_in_maintenance field indicates whether the entity is in maintenance mode. If it is true, the maintenances array contains associated active and planned maintenance windows whose end times have not yet passed. Each window includes its ID, name, start time, and end time.

Deprecated Requests for Available Dimensions

Deprecated

The GET _core/rsm/maintenance/metric_dimensions/{metric_id} request returned the dimensions of a specific metric, its maintenance status, and associated maintenance windows.

The GET _core/rsm/maintenance/metric_dimensions/ request was used to get dimensions for all metrics and build the maintenance condition form.

Both requests are deprecated. Use GET _core/rsm/parent_metrics/{metric_id}/entities?include_linked_info=true instead.

Description​

Maintenance Window States​

CRUD Operations​

Creating a Maintenance Window​

Request​

Request Parameters​

Updating a Maintenance Window​

Request​

Request Parameters​

Cancelling a Maintenance Window​

Request​

Completing a Maintenance Window Manually​

Request​

Getting the Maintenance Window List​

Request​

Getting a Maintenance Window​

Request​

Response Example​

Main Response Fields​

Deleting a Maintenance Window​

Request​

Display and Preview Requests​

Checking Metric Coverage​

Coverage Check Request​

Request​

Request Parameters​

Response Example​

Main Response Fields​

Getting Metrics by Dimensions​

Request​

Getting Filter Value Suggestions​

Request​

Response Example​

Getting Global Metric Entities​

Request​

Response Example​

Deprecated Requests for Available Dimensions​

Description

Maintenance Window States

CRUD Operations

Creating a Maintenance Window

Request

Request Parameters

Updating a Maintenance Window

Request

Request Parameters

Cancelling a Maintenance Window

Request

Completing a Maintenance Window Manually

Request

Getting the Maintenance Window List

Request

Getting a Maintenance Window

Request

Response Example

Main Response Fields

Deleting a Maintenance Window

Request

Display and Preview Requests

Checking Metric Coverage

Coverage Check Request

Request

Request Parameters

Response Example

Main Response Fields

Getting Metrics by Dimensions

Request

Getting Filter Value Suggestions

Request

Response Example

Getting Global Metric Entities

Request

Response Example

Deprecated Requests for Available Dimensions