---
title: "Get the maintenance windows of the organization"
method: GET
path: "/maintenance-windows"
tags: ["Maintenance windows"]
---

# Get the maintenance windows of the organization

`GET /maintenance-windows`

## Request

- Base URL: `https://api.theo.live/v2`
- URL: `https://api.theo.live/v2/maintenance-windows`
- Auth: HTTP basic

Maintenance windows are recurring time slots (in UTC) during which the organization allows THEO to perform maintenance on its long-running engines. Maintenance means moving an engine to fresh infrastructure: the engine is restarted with the same configuration, the stream is briefly interrupted (viewers see a clean end of stream) and the contributing encoder reconnects. The same applies to push and pull ingests on the shared ingest infrastructure: when the infrastructure carrying such an ingest is retired, the ingest is moved inside a window (the encoder reconnects to the same ingest URL, or the source is pulled again). Maintenance is only performed on engines and ingests that need it, one per channel at a time, and always inside a window. A window recurs every week, or only in selected weeks of the month (e.g. the second tuesday of the month); together the windows must offer a maintenance opportunity at least once a month. There is no default: when no windows are configured, THEO has no maintenance opportunity for the organization and maintenance that is needed stays pending. Engines and ingests report their pending or ongoing maintenance in their `maintenance` field, and the `engine.maintenance.*` / `ingest.maintenance.*` webhook events announce every step. Configuring windows does not schedule any restarts by itself.

## Response `200`

Maintenance window settings, including the last maintenance performed, the next (or ongoing) window occurrence, and the maintenance that is pending or in progress

- MaintenanceWindowsResult
  - `data` OrganizationMaintenanceWindows, required: Maintenance window settings of the organization
    - `windows` MaintenanceWindow[], required: The configured windows of the organization. Empty when none are configured, in which case THEO has no maintenance opportunity
      - `dayOfWeek` 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sunday', required: Day of the week (in UTC) on which the window starts
      - `startTime` string, required: Start time of the window in 'HH:mm' 24-hour format, UTC
      - `durationMinutes` integer, required: Duration of the window in minutes (15-1440). The window may extend past midnight into the next day
      - `weeksOfMonth` union[]: Weeks of the month in which the window occurs: 1-4 for the n-th occurrence of the day in the month, 'last' for the last one (e.g. [2] for "the second tuesday of the month", [1, 3] for roughly every other week). Omitted means the window recurs every week
        - union
          - 1
          - 2
          - 3
          - 4
          - 'last'
    - `lastMaintenanceAt` string: Timestamp of the last maintenance performed by THEO (ISO 8601, UTC)
    - `nextWindow` object: The next (or currently ongoing) occurrence of the configured windows. Absent when no windows are configured
      - `start` string, required: Start of the occurrence (ISO 8601, UTC)
      - `end` string, required: End of the occurrence (ISO 8601, UTC)
    - `pending` MaintenanceSummary, required: Maintenance that is needed and will be performed in the next maintenance window
      - `count` integer, required: Number of engines (including those controlled by an ingest) and ingests concerned
      - `engineIds` string[], required: Engines concerned
      - `ingestIds` string[], required: Ingests concerned: ingests that are started/stopped via the ingest (such as rtsp-pull), and push/pull ingests on the shared ingest infrastructure that have to move
    - `inProgress` object, required: Maintenance currently being performed
      - `count` integer, required: Number of engines (including those controlled by an ingest) and ingests concerned
      - `engineIds` string[], required: Engines concerned
      - `ingestIds` string[], required: Ingests concerned: ingests that are started/stopped via the ingest (such as rtsp-pull), and push/pull ingests on the shared ingest infrastructure that have to move

## Changes

- **2026-10-26** `5f4413af6d13`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/dolby/apis/theolive-api/changes/maintenance-windows/get.md)

---

[API](https://skmtc.dev/dolby/apis/theolive-api.md) - [All operations](https://skmtc.dev/dolby/apis/theolive-api/llms.txt) - [OpenAPI document](https://skmtc.dev/dolby/apis/theolive-api/revisions/baabda2927db?raw)