> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudcruise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Window

> Only start a workflow's runs during the hours you choose, and hold the rest until the window next opens

Some portals are only staffed or only safe to automate at certain times. A run window sets the times a workflow's runs may start. A run submitted outside those times is accepted, held, and started when the window opens.

The run window is stored on the workflow as `run_window`. You can edit them in the dashboard under a workflow's **General** tab, or with the [Run Window API](/workflow-api/get-run-window).

## How it works

* A workflow without a run window behaves as before. Runs start whenever a worker is free.
* With a run window, a run submitted while the window is **closed** gets the status [`execution.paused`](/concepts/run-statuses) and the pause reason `run_window`. It starts when the window next opens.
* A run that is already running when the window closes **finishes**. A run window only controls when runs start.
* The run window is checked live and is not part of a workflow version. Changing it applies at once to runs that are already queued. This differs from other workflow edits, which a run fixes when it is submitted.
* Deleting the run window releases every held run.

## Defining the window

All times are in one IANA time zone, for example `America/Chicago`. Daylight saving changes are handled for you.

```json theme={null}
{
  "time_zone": "America/Chicago",
  "regular_hours": [
    {
      "active_start_day": "MONDAY",
      "active_start_time": { "hours": 7 },
      "active_end_day": "MONDAY",
      "active_end_time": { "hours": 17 }
    }
  ],
  "special_hours": [
    {
      "label": "Thanksgiving",
      "start_date": { "year": 2026, "month": 11, "day": 26 },
      "end_date": { "year": 2026, "month": 11, "day": 27 },
      "active": false
    }
  ]
}
```

### Regular hours

`regular_hours` is the weekly schedule. Each entry is one period with a start day and time and an end day and time. Add several entries to a day for split shifts, such as 8:00–12:00 and 13:00–17:00.

| Field | Meaning |
| - | - |
| `active_start_day`, `active_end_day` | A day name in capitals, `MONDAY` to `SUNDAY`. |
| `active_start_time`, `active_end_time` | `{ "hours": 0-23, "minutes": 0-59 }`. `minutes` is optional and defaults to 0. |

A period belongs to the day it **starts**. It may run overnight: set `active_end_day` to the next day, for example Friday 22:00 to Saturday 06:00. The end must come after the start on the same day, or fall on the following day. Periods that span more than one night are not allowed.

### Special hours

`special_hours` overrides the weekly schedule for particular dates. Each entry is either **dated** or **recurring**, and either **opens** the hours (`active: true`, with `active_start_time` and `active_end_time`) or **closes** them for the whole day (`active: false`).

| Entry | Fields |
| - | - |
| Dated | `start_date` and optional `end_date`, each `{ "year", "month", "day" }`. A missing `end_date` means a single day. |
| Recurring | `recurrence`, an [RFC 5545](https://datatracker.ietf.org/doc/html/rfc5545) rule such as `FREQ=MONTHLY;BYDAY=1SA`, and `recurrence_start`, the first date the series may apply. Only `DAILY`, `WEEKLY`, `MONTHLY` and `YEARLY` frequencies are supported. |
| Both | `label` (optional name shown in the dashboard), `active`, and when `active` is `true`, `active_start_time` and `active_end_time`. Special hours do not run overnight: the end must be after the start. |

An entry must be dated **or** recurring, never both. If `recurrence_start` is not a date the rule produces, the API accepts the window and returns a warning. The date then only acts as the earliest day the series may start.

### Which rule wins

For any given date, the first of these that matches decides the hours for that date:

1. **Dated special hours.**
2. **Recurring special hours.**
3. **Regular hours.**

A matching special entry replaces the weekly schedule for the whole date, not just part of it. A closing entry (`active: false`) therefore makes the whole date closed.

A window needs at least one regular period or one active special entry. Otherwise it would never open, and the API rejects it. To remove the restriction, delete the run window instead.

## Run now

Sometimes a run has to start outside the window. In the dashboard, a workflow whose window is closed appears under **Runs → Paused Resources**. **Run now** lifts the window for that workflow.

* It starts every run already held, and every run submitted while the lift is active.
* The lift lasts until the window next opens, or until you edit or delete it.
* You can do the same through the API with [`POST /runs/unpause`](/run-api/unpause-runs) and `pause_resource` set to `run_window`.

## Interaction with other pauses

* A run window never lifts a manual pause. A run held by both a pause and a closed window stays held until both allow it.
* **Unpause All** skips run-window holds. Use **Run now** to lift them.
* The pause reason on a held run, shown in the dashboard's **Paused runs** list, includes when the window next opens.

## Example: staffed portal

A portal that is only staffed 7 AM to 5 PM Central on weekdays, and closed on Thanksgiving:

```json theme={null}
{
  "time_zone": "America/Chicago",
  "regular_hours": [
    { "active_start_day": "MONDAY", "active_start_time": { "hours": 7 }, "active_end_day": "MONDAY", "active_end_time": { "hours": 17 } },
    { "active_start_day": "TUESDAY", "active_start_time": { "hours": 7 }, "active_end_day": "TUESDAY", "active_end_time": { "hours": 17 } },
    { "active_start_day": "WEDNESDAY", "active_start_time": { "hours": 7 }, "active_end_day": "WEDNESDAY", "active_end_time": { "hours": 17 } },
    { "active_start_day": "THURSDAY", "active_start_time": { "hours": 7 }, "active_end_day": "THURSDAY", "active_end_time": { "hours": 17 } },
    { "active_start_day": "FRIDAY", "active_start_time": { "hours": 7 }, "active_end_day": "FRIDAY", "active_end_time": { "hours": 17 } }
  ],
  "special_hours": [
    {
      "label": "Thanksgiving",
      "start_date": { "year": 2026, "month": 11, "day": 26 },
      "active": false
    },
    {
      "label": "First Saturday backlog",
      "recurrence": "FREQ=MONTHLY;BYDAY=1SA",
      "recurrence_start": { "year": 2026, "month": 11, "day": 1 },
      "active": true,
      "active_start_time": { "hours": 9 },
      "active_end_time": { "hours": 14 }
    }
  ]
}
```

A run submitted on Friday at 6 PM stays `execution.paused` until Monday at 7 AM Central, then starts.

## Setting it up

**1. Dashboard**

Open the workflow, go to **General**, and turn on **Run window**. Pick a time zone, set the weekly hours, add any special dates, and save the workflow. The page shows **Active now**, or when the window next opens.

**2. API**

Send the JSON above with [Set run window](/workflow-api/set-run-window). The response includes warnings and whether the window is open now. `run_window` is also accepted on workflow save, create, import and fork, and is included in workflow exports.

> [!NOTE]
>
> `run_window` is part of the complete workflow JSON. When you save a workflow with [Update workflow](/workflow-api/update-workflow), leaving `run_window` out keeps the current run window, and sending `null` removes it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.