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

# Schedules

> Put a plan on a schedule so it runs itself — hourly, daily, weekly, monthly, or once at a future time

## Overview

A schedule is a property of a plan: each plan can have one schedule that runs it automatically on a cadence, or once at a future time. Instead of triggering runs by hand, put your regression suite on a daily schedule and let Roark catch regressions before you do.

There is no separate schedules page — you create and manage a schedule in two places:

* **While creating a run** — the split button next to **Run simulation** offers **Schedule recurring…** and **Run once, later…**
* **On the plan detail page** — the **Automation** panel (or the **Schedule this plan** call-to-action if the plan runs on demand)

Scheduled executions show up as ordinary runs in the runs hub, tagged with a **Schedule** trigger chip.

***

## Scheduling from the create-run page

<Steps>
  <Step title="Configure the run">
    Set up agents, template, flows, and settings as usual on **Simulations → New Run**.
  </Step>

  <Step title="Save it as a plan">
    Check **Save as plan** in the footer and name the plan. A schedule belongs to a plan, so the configuration needs to be saved.
  </Step>

  <Step title="Pick when it runs">
    Open the chevron menu on the primary button and choose **Schedule recurring…** (run on a cadence) or **Run once, later…** (run a single time in the future). The button face changes from **Run simulation** to **Schedule**.
  </Step>

  <Step title="Set the cadence">
    An inline **Schedule** section appears with frequency, time, timezone, day selection, and end condition. A live sentence summarizes your choices — for example, "Every weekday at 9:00 AM, ET · ends never".
  </Step>

  <Step title="Create the schedule">
    Press **Schedule** (or <kbd>⌘</kbd>+<kbd>↵</kbd>). The plan is saved and its first run fires at the next scheduled time.
  </Step>
</Steps>

***

## Scheduling from a plan

On a plan's detail page:

* If the plan has no schedule, you'll see a **Runs on demand** card: "This plan only runs when you start it. Put it on a schedule and it'll run itself — catching regressions before you do." Click **Schedule this plan**, set the cadence, and click **Create schedule**.
* If the plan already has a schedule, the **Automation** panel shows it — each plan has exactly one schedule.

***

## Cadence options

### Frequencies

| Frequency   | Behavior                                                    | Example                |
| :---------- | :---------------------------------------------------------- | :--------------------- |
| **Hourly**  | Runs every hour at a set minute                             | :30 past each hour     |
| **Daily**   | Runs once per day at a set time                             | Every day at 9:00 AM   |
| **Weekly**  | Runs on the days you pick (**On these days**) at a set time | Mon and Fri at 2:00 PM |
| **Monthly** | Runs on a day of the month at a set time                    | The 15th at 10:00 AM   |
| **Once**    | Runs a single time at a future date and time                | Dec 1 at 3:00 PM       |

### Time and timezone

Pick the time of day and a timezone from the curated list. Schedules follow the selected timezone, so choose the one your team works in — the live sentence and **Next run** label confirm exactly when the next execution lands.

### End conditions

| Option           | Description                            | Typical use                  |
| :--------------- | :------------------------------------- | :--------------------------- |
| **Never**        | Runs indefinitely                      | Continuous monitoring        |
| **On a date**    | Stops after a specific date            | Campaign or seasonal testing |
| **After N runs** | Stops after a set number of executions | Trialing a new schedule      |

***

## Managing a schedule

The plan's **Automation** panel is where you manage an existing schedule:

* **Status badge** — **Active** or **Paused**
* **Pause / Resume** — pause without losing the configuration, resume when ready
* **Edit** — change the cadence, time, timezone, or end condition
* **Delete** — remove the schedule entirely (with a confirmation step); the plan and its run history stay intact
* **Next run / Last run** — when the schedule fires next and when it last ran

<Note>
  Editing an active schedule recalculates the next run time from your new settings.
</Note>

***

## Scheduled runs in the runs hub

There is no separate job history per schedule. Each scheduled execution is a normal run:

* It appears in the plan's **Run history** and in the runs hub, labelled **SR-{'{n}'}** like any other run
* It carries a **Schedule** trigger chip, distinguishing it from **Manual**, **Re-run**, and **System** runs
* It moves through the usual run statuses: **Running**, **Queued**, **Completed**, **Failed**, **Cancelled**

<Warning>
  If any variable in the plan lacks a default value, scheduled runs can't prompt for it at execution time. Set defaults for every variable before scheduling. See [Variables](/documentation/simulation-testing/variables).
</Warning>

***

## Best practices

<AccordionGroup>
  <Accordion title="Start with lower frequencies">
    Begin with daily or weekly schedules to validate the plan before moving to hourly.
  </Accordion>

  <Accordion title="Use end conditions when trialing">
    Set **After N runs** on a new schedule to limit usage while you confirm the configuration.
  </Accordion>

  <Accordion title="Watch the first few runs">
    Check the first scheduled runs in the runs hub to confirm agents connect and checks behave as expected.
  </Accordion>

  <Accordion title="Stagger heavy plans">
    Avoid scheduling multiple high-concurrency plans at the same time.
  </Accordion>

  <Accordion title="Pause instead of delete">
    Pausing keeps the cadence configured so you can resume with one click — deleting means re-creating it later.
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

**Schedule not firing**

* Check the **Automation** panel — the badge should read **Active**, not **Paused**
* Verify the timezone matches your expectation; the **Next run** label shows the exact upcoming time
* Confirm the end condition hasn't been reached (past its end date, or the run count is exhausted)

**Scheduled runs failing**

* Open the failed run from the plan's **Run history** and review the report
* Verify the plan's agents and endpoints are still reachable
* Make sure every variable in the plan has a default value

***

## Next steps

<CardGroup cols={2}>
  <Card title="Run Plans" icon="list-checks" href="/documentation/simulation-testing/run-plans">
    Build the plans your schedules execute
  </Card>

  <Card title="Running Simulations" icon="play" href="/documentation/simulation-testing/running-simulations">
    Follow runs live and read the report
  </Card>

  <Card title="Customer Flows" icon="route" href="/documentation/simulation-testing/customer-flows">
    Design the conversations your plans test
  </Card>

  <Card title="Variables" icon="braces" href="/documentation/simulation-testing/variables">
    Set defaults so scheduled runs never stall
  </Card>
</CardGroup>