---
title: NerdGraph tutorial: Manage service level maintenance windows
source: https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-maintenance-windows-slm
---

## Create a maintenance window [#create-mutation]

Use the `maintenanceWindowCreate` mutation to create a new maintenance window for your service levels.

### Parameters [#create-parameters]

| Parameter            | Data type            | Description                                                                                                                                                                 |
| -------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`               | String               | (Required) The name of the maintenance window.                                                                                                                              |
| `description`        | String               | (Optional) A description of the maintenance window.                                                                                                                         |
| `scope`              | ScopedReferenceInput | (Required) The scope the maintenance window belongs to. Contains `id` (the account ID) and `type` (the entity scope — use `ACCOUNT` for service level maintenance windows). |
| `startTime`          | NaiveDateTime        | (Required) The start time of the maintenance window in ISO 8601 format. This time should be interpreted in the timezone specified in the `timezone` parameter.              |
| `duration`           | Duration             | (Required) The duration of the maintenance window in ISO 8601 duration format (for example, `PT2H` for 2 hours, `PT30M` for 30 minutes).                                    |
| `rrule`              | String               | (Optional) The recurrence rule of the maintenance window in iCalendar format (RFC 5545). Use this to create recurring maintenance windows.                                  |
| `timezone`           | String               | (Required) The timezone of the maintenance window (for example, `America/New_York`, `Europe/London`).                                                                       |
| `affectedEntityType` | String               | (Required) The type of the affected entities. Use `SERVICE_LEVEL` for service level maintenance windows.                                                                    |
| `affectedEntities`   | \[ID]                | (Optional) The list of entity GUIDs affected by the maintenance window.                                                                                                     |

### Sample mutation [#create-sample]

```graphql
mutation {
  maintenanceWindowCreate(
    maintenanceWindow: {
      name: "Monthly System Upgrade"
      description: "Scheduled maintenance for system upgrades"
      scope: { id: "INSERT_YOUR_ACCOUNT_ID", type: ACCOUNT }
      startTime: "2025-12-15T02:00:00"
      duration: "PT4H"
      rrule: "FREQ=MONTHLY;BYMONTHDAY=15"
      timezone: "America/New_York"
      affectedEntityType: "SERVICE_LEVEL"
      affectedEntities: ["INSERT_ENTITY_GUID_1", "INSERT_ENTITY_GUID_2"]
    }
  ) {
    id
    name
    description
    startTime
    duration
    rrule
    timezone
    affectedEntityType
    affectedEntities
  }
}
```

## Update a maintenance window [#update-mutation]

Use the `maintenanceWindowUpdate` mutation to update an existing maintenance window.

### Parameters [#update-parameters]

| Parameter          | Data type     | Description                                                                 |
| ------------------ | ------------- | --------------------------------------------------------------------------- |
| `id`               | ID            | (Required) The unique identifier of the maintenance window to update.       |
| `name`             | String        | (Optional) The new name of the maintenance window.                          |
| `description`      | String        | (Optional) The new description of the maintenance window.                   |
| `startTime`        | NaiveDateTime | (Optional) The new start time in ISO 8601 format.                           |
| `duration`         | Duration      | (Optional) The new duration in ISO 8601 duration format.                    |
| `rrule`            | String        | (Optional) The new recurrence rule in iCalendar format.                     |
| `timezone`         | String        | (Optional) The new timezone.                                                |
| `affectedEntities` | \[ID]         | (Optional) The new list of entity GUIDs affected by the maintenance window. |

### Sample mutation [#update-sample]

```graphql
mutation {
  maintenanceWindowUpdate(
    id: "INSERT_MAINTENANCE_WINDOW_ID"
    maintenanceWindow: {
      name: "Updated System Upgrade Window"
      duration: "PT6H"
      affectedEntities: [
        "INSERT_ENTITY_GUID_1"
        "INSERT_ENTITY_GUID_2"
        "INSERT_ENTITY_GUID_3"
      ]
    }
  ) {
    id
    name
    description
    startTime
    duration
    rrule
    timezone
    affectedEntityType
    affectedEntities
  }
}
```

## Delete a maintenance window [#delete-mutation]

Use the `maintenanceWindowDelete` mutation to delete a maintenance window.

### Sample mutation [#delete-sample]

```graphql
mutation {
  maintenanceWindowDelete(id: "INSERT_MAINTENANCE_WINDOW_ID") {
    id
    name
  }
}
```

## Query maintenance windows by IDs [#query-by-ids]

Use the `listByIds` query to retrieve specific maintenance windows by their IDs.

### Sample query [#query-ids-sample]

```graphql
query {
  actor {
    maintenanceWindow {
      listByIds(
        ids: [
          "INSERT_MAINTENANCE_WINDOW_ID_1"
          "INSERT_MAINTENANCE_WINDOW_ID_2"
        ]
      ) {
        maintenanceWindows {
          id
          name
          description
          startTime
          duration
          rrule
          timezone
          affectedEntityType
          affectedEntities
          scope {
            id
            type
          }
          metadata {
            createdAt
            createdBy
            updatedAt
            updatedBy
          }
        }
      }
    }
  }
}
```

## Query maintenance windows by affected entity [#query-by-entity]

Use the `listByAffectedEntityId` query to retrieve all maintenance windows that affect a specific entity.

### Sample query [#query-entity-sample]

```graphql
query {
  actor {
    maintenanceWindow {
      listByAffectedEntityId(affectedEntityId: "INSERT_ENTITY_GUID") {
        maintenanceWindows {
          id
          name
          description
          startTime
          duration
          rrule
          timezone
          affectedEntityType
          affectedEntities
        }
      }
    }
  }
}
```

## Related topics [#related-topics]

[Service level maintenance windows](https://docs.newrelic.com/docs/service-level-management/maintenance-windows-slm/intro)

Learn what maintenance windows are and how they work.

[Schedule and manage maintenance windows](https://docs.newrelic.com/docs/service-level-management/maintenance-windows-slm/schedule)

Learn how to create, edit, and delete maintenance windows in the UI.

[NerdGraph tutorial: Configure service levels](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-slm)

Learn how to create and manage SLIs and SLOs with NerdGraph.