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

# oqoqo schedules

> Preview, create, change, pause, resume, launch, and delete schedules that launch a finished experiment again on a cron cadence, from the CLI.

A schedule launches a finished experiment again on a cron cadence, so you can track agents over time. Each launch uses the project as it is then: the latest tasks, treatments, files, and machines. Who a schedule runs as and when Oqoqo pauses it are on [Schedules](https://docs.oqoqo.ai/experiments/schedules.md).

## Rules for every change

These rules hold in the CLI and the plugin.

* **Launch check.** A create, a resume, or a change to the experiment, `--cron`, or `--time-zone` first checks the launch as you. If anything blocks it, the command refuses with `schedule_launch_blocked` and lists every blocker with its fix link, the same ones [`oqoqo schedules preview`](#oqoqo-schedules-preview) shows. When the check passes, the schedule runs as you.
* **Paused schedules stay paused.** A passing check clears the reason Oqoqo paused a schedule, but it stays paused until you resume it. `oqoqo schedules update` prints the resume command.
* **One launch at a time.** [`oqoqo schedules launch`](#oqoqo-schedules-launch) refuses with `experiment_schedule_run_active` while the schedule's last experiment still runs.
* **50 active schedules.** A create or resume past that returns `schedule_limit_reached`.
* **Lock versions.** Every change after create takes the `--lock-version` from `oqoqo schedules get`, so two people can't overwrite each other's edits; a stale value fails with `schedule_changed`.
* **Attempt IDs.** Create and update take an `--attempt-id`, so a retry after a lost response is the same change. Reusing an ID for a different change fails with `schedule_attempt_reused`.

## Time zones

The cron has five fields (minute, hour, day of month, month, day of week) and always reads in the schedule's time zone. For example, `0 9 * * 1-5` is 9:00 AM on weekdays. The minute must be `0`, `15`, `30`, or `45`, so a schedule launches at most once an hour, on the quarter hour.

`--time-zone` (with a hyphen) takes an IANA name, such as `America/New_York`, or `UTC`. It's required on create because AI assistants and CI machines often run in UTC, and the error suggests your machine's time zone.

| You pass | Oqoqo |
| - | - |
| An abbreviation, such as `EST` or `BST` | Refuses it and asks for an IANA name, because an abbreviation can name a zone you didn't mean |
| `GMT` or `Etc/GMT` | Stores `UTC` |
| An older name, such as `US/Pacific` or `Asia/Calcutta` | Stores its current name, such as `America/Los_Angeles` or `Asia/Kolkata` |

## oqoqo schedules preview

Preview when a new or changed schedule launches, the runs it uses, and what would stop it.

```bash theme={null}
oqoqo schedules preview [experiment-id] [flags]
```

**Plugin (MCP) tool:** [`preview_schedule`](https://docs.oqoqo.ai/mcp-server/schedules#preview_schedule)

**Arguments**

| Argument | Description |
| - | - |
| `[experiment-id]` | The finished `exp_` experiment to launch. Required for a new schedule. With `--schedule-id`, leave it out to keep the schedule's experiment. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--cron` | string | | Five cron fields; the minute is `0`, `15`, `30`, or `45`. Required for a new schedule. |
| `--time-zone` | string | | The IANA time zone the cron reads in, or `UTC`. Required for a new schedule. |
| `--schedule-id` | string | | Preview a change to this `sch_` schedule. What you leave out keeps the schedule's own value. |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Preview a new weekday schedule:

```bash theme={null}
oqoqo schedules preview exp_8f2c41d0 --cron "0 9 * * 1-5" --time-zone America/Los_Angeles
```

Preview moving a schedule one hour later:

```bash theme={null}
oqoqo schedules preview --schedule-id sch_c0a9f311 --cron "0 10 * * 1-5"
```

**Result fields**

| Field | Description |
| - | - |
| `cadenceDescription` | The cadence in plain words. |
| `timeZone`, `timeZoneLabel` | The time zone that Oqoqo stores, and its name in plain words. |
| `nextLaunches` | The next 3 launches. |
| `runsPerLaunch`, `runsPer30Days`, `shortfall` | The runs the schedule uses, and when your runs fall short, as [Schedule fields](#schedule-fields) describes. |
| `blockers` | Everything that would stop a launch now, each with a `code`, a `message`, and an `action` link that fixes it. Empty when the schedule can launch. |
| `blocker` | The first of `blockers`, kept for older CLI releases. Use `blockers`. |

**Notes**

The preview changes nothing and checks the launch as you. A paused schedule's preview shows the launches it would have once you resume it.

## oqoqo schedules create

Schedule a finished experiment to launch again on a cadence.

```bash theme={null}
oqoqo schedules create <experiment-id> --cron <cron> --time-zone <zone> [flags]
```

**Plugin (MCP) tool:** [`manage_schedule`](https://docs.oqoqo.ai/mcp-server/schedules#manage_schedule)

Each scheduled launch spends runs from your organization's balance. In Ask Oqo, you approve each call.

**Arguments**

| Argument | Description |
| - | - |
| `<experiment-id>` | Required. The finished `exp_` experiment to launch. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--cron` | string | | Required. Five cron fields; the minute is `0`, `15`, `30`, or `45`. |
| `--time-zone` | string | | Required. The IANA time zone the cron reads in, or `UTC`. |
| `--name` | string | The experiment's name | The schedule's name, up to 120 characters. |
| `--attempt-id` | string | | An ID you choose, so that a retry doesn't repeat the change. 16 to 200 letters, digits, `-`, or `_`. Without it, the CLI makes one and prints it on stderr. |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Launch the experiment again at 9:00 AM Pacific every weekday:

```bash theme={null}
oqoqo schedules create exp_8f2c41d0 --cron "0 9 * * 1-5" --time-zone America/Los_Angeles --name "Weekday checkout"
```

**Result fields**

| Field | Description |
| - | - |
| `schedule` | The schedule: `scheduleId`, `name`, `status`, `needsAttention`, `pauseReason`, `cron`, `timeZone`, `cadenceDescription`, `timeZoneLabel`, `nextRunAt`, `sourceExperiment`, `runsAs`, `runsPerLaunch`, `runsPer30Days`, `shortfall`, `lastResult`, `skippedInARow`, `lastExperiment`, `lockVersion`, and `dashboardUrl`. [Schedule fields](#schedule-fields) describes each one. |

**Notes**

The schedule runs as you and checks the conditions under [Rules for every change](#rules-for-every-change).

## oqoqo schedules list

List the project's schedules.

```bash theme={null}
oqoqo schedules list [flags]
```

**Plugin (MCP) tool:** [`list_schedules`](https://docs.oqoqo.ai/mcp-server/schedules#list_schedules)

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--query` | string | | Search text, up to 200 characters, such as part of a schedule's name. |
| `--status` | `active`, `paused` | | Schedules with this status. |
| `--experiment-id` | string | | Schedules that launch this `exp_` experiment again. |
| `--launched-experiment-id` | string | | The schedule that launched this `exp_` experiment. |
| `--limit` | integer | `50` | Results per page, up to 200 (default 50). |
| `--cursor` | string | | The `nextCursor` from the previous page. |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Find the schedule that launched an experiment:

```bash theme={null}
oqoqo schedules list --launched-experiment-id exp_d41a7c09
```

**Result fields**

| Field | Description |
| - | - |
| `schedules` | Each schedule: `scheduleId`, `name`, `status`, `needsAttention`, `pauseReason`, `cron`, `timeZone`, `cadenceDescription`, `timeZoneLabel`, `nextRunAt`, `sourceExperiment`, `runsAs`, `runsPerLaunch`, `runsPer30Days`, `shortfall`, `lastResult`, `skippedInARow`, `lastExperiment`, `lockVersion`, and `dashboardUrl`. [Schedule fields](#schedule-fields) describes each one. |
| `hasMore`, `nextCursor` | Whether another page exists, and the cursor for it. |

**Notes**

Text output shows `needs attention` for a schedule that Oqoqo paused. To list the experiments a schedule launched, run `oqoqo experiments list --schedule-id`. `oqoqo experiments get` also names the schedule that launched an experiment, in `lineage.schedule`.

## oqoqo schedules get

Read one schedule.

```bash theme={null}
oqoqo schedules get <schedule-id> [flags]
```

**Plugin (MCP) tool:** [`get_schedule`](https://docs.oqoqo.ai/mcp-server/schedules#get_schedule)

**Arguments**

| Argument | Description |
| - | - |
| `<schedule-id>` | Required. The `sch_` schedule ID. |

Takes only the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Read the `lockVersion` before a change:

```bash theme={null}
oqoqo schedules get sch_c0a9f311 --output json
```

**Result fields**

| Field | Description |
| - | - |
| `schedule` | The schedule: `scheduleId`, `name`, `status`, `needsAttention`, `pauseReason`, `cron`, `timeZone`, `cadenceDescription`, `timeZoneLabel`, `nextRunAt`, `sourceExperiment`, `runsAs`, `runsPerLaunch`, `runsPer30Days`, `shortfall`, `lastResult`, `skippedInARow`, `lastExperiment`, `lockVersion`, and `dashboardUrl`. [Schedule fields](#schedule-fields) describes each one. |

**Notes**

Text output shows the status, the cadence, the next launch in the schedule's time zone, the runs it uses, who it runs as, the last experiment, and the lock version.

## oqoqo schedules update

Change a schedule's name, cadence, time zone, or experiment.

```bash theme={null}
oqoqo schedules update <schedule-id> --lock-version <n> [flags]
```

**Plugin (MCP) tool:** [`manage_schedule`](https://docs.oqoqo.ai/mcp-server/schedules#manage_schedule)

Each scheduled launch spends runs from your organization's balance. In Ask Oqo, you approve each call.

**Arguments**

| Argument | Description |
| - | - |
| `<schedule-id>` | Required. The `sch_` schedule ID. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--lock-version` | integer | | Required. The `lockVersion` from `oqoqo schedules get`. |
| `--name` | string | | A new name, up to 120 characters. Without it, a schedule still named after its experiment takes the new experiment's name when you change the experiment. |
| `--cron` | string | | Five cron fields; the minute is `0`, `15`, `30`, or `45`. |
| `--time-zone` | string | | The IANA time zone the cron reads in, or `UTC`. |
| `--experiment-id` | string | | A finished `exp_` experiment to launch instead. |
| `--attempt-id` | string | | An ID you choose, so that a retry doesn't repeat the change. 16 to 200 letters, digits, `-`, or `_`. Without it, the CLI makes one and prints it on stderr. |

Pass at least one of `--name`, `--cron`, `--time-zone`, or `--experiment-id`. Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Move a schedule to 10:00 AM:

```bash theme={null}
oqoqo schedules update sch_c0a9f311 --lock-version 3 --cron "0 10 * * 1-5"
```

**Result fields**

| Field | Description |
| - | - |
| `schedule` | The schedule: `scheduleId`, `name`, `status`, `needsAttention`, `pauseReason`, `cron`, `timeZone`, `cadenceDescription`, `timeZoneLabel`, `nextRunAt`, `sourceExperiment`, `runsAs`, `runsPerLaunch`, `runsPer30Days`, `shortfall`, `lastResult`, `skippedInARow`, `lastExperiment`, `lockVersion`, and `dashboardUrl`. [Schedule fields](#schedule-fields) describes each one. |

**Notes**

The command changes only the flags you pass, and renaming alone doesn't change who the schedule runs as. A change to the experiment, `--cron`, or `--time-zone` gets the [launch check](#rules-for-every-change); preview it first with `oqoqo schedules preview --schedule-id`.

## oqoqo schedules pause

Pause a schedule. It does not launch until you resume it.

```bash theme={null}
oqoqo schedules pause <schedule-id> --lock-version <n> [flags]
```

**Plugin (MCP) tool:** [`manage_schedule`](https://docs.oqoqo.ai/mcp-server/schedules#manage_schedule)

In Ask Oqo, you approve each call.

**Arguments**

| Argument | Description |
| - | - |
| `<schedule-id>` | Required. The `sch_` schedule ID. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--lock-version` | integer | | Required. The `lockVersion` from `oqoqo schedules get`. |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

```bash theme={null}
oqoqo schedules pause sch_c0a9f311 --lock-version 3
```

**Result fields**

| Field | Description |
| - | - |
| `schedule` | The schedule: `scheduleId`, `name`, `status`, `needsAttention`, `pauseReason`, `cron`, `timeZone`, `cadenceDescription`, `timeZoneLabel`, `nextRunAt`, `sourceExperiment`, `runsAs`, `runsPerLaunch`, `runsPer30Days`, `shortfall`, `lastResult`, `skippedInARow`, `lastExperiment`, `lockVersion`, and `dashboardUrl`. [Schedule fields](#schedule-fields) describes each one. |

**Notes**

Pausing a paused schedule changes nothing. See [Rules for every change](#rules-for-every-change).

## oqoqo schedules resume

Resume a paused schedule. It runs as you from its next launch time.

```bash theme={null}
oqoqo schedules resume <schedule-id> --lock-version <n> [flags]
```

**Plugin (MCP) tool:** [`manage_schedule`](https://docs.oqoqo.ai/mcp-server/schedules#manage_schedule)

Each scheduled launch spends runs from your organization's balance. In Ask Oqo, you approve each call.

**Arguments**

| Argument | Description |
| - | - |
| `<schedule-id>` | Required. The `sch_` schedule ID. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--lock-version` | integer | | Required. The `lockVersion` from `oqoqo schedules get`. |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

```bash theme={null}
oqoqo schedules resume sch_c0a9f311 --lock-version 4
```

**Result fields**

| Field | Description |
| - | - |
| `schedule` | The schedule: `scheduleId`, `name`, `status`, `needsAttention`, `pauseReason`, `cron`, `timeZone`, `cadenceDescription`, `timeZoneLabel`, `nextRunAt`, `sourceExperiment`, `runsAs`, `runsPerLaunch`, `runsPer30Days`, `shortfall`, `lastResult`, `skippedInARow`, `lastExperiment`, `lockVersion`, and `dashboardUrl`. [Schedule fields](#schedule-fields) describes each one. |

**Notes**

Resume runs the [launch check](#rules-for-every-change). If something blocks it, the schedule stays paused and `details.blockers` lists every blocker, with the same fields as the preview's `blockers`; fix them and run the same command again. Resuming never starts a launch right away, and resuming an active schedule changes nothing.

## oqoqo schedules launch

Launch the schedule's experiment now, as you.

```bash theme={null}
oqoqo schedules launch <schedule-id> [flags]
```

**Plugin (MCP) tool:** [`rerun_experiment`](https://docs.oqoqo.ai/mcp-server/experiments#rerun_experiment) with `schedule_id`

This command spends runs from your organization's balance. In Ask Oqo, you approve each call.

**Arguments**

| Argument | Description |
| - | - |
| `<schedule-id>` | Required. The `sch_` schedule ID. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--attempt-id` | string | | An ID you choose, so that a retry doesn't repeat the change. 1 to 100 characters. Without it, the CLI makes one and prints it on stderr. |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

```bash theme={null}
oqoqo schedules launch sch_c0a9f311 --output json
```

**Result fields**

The same fields as [`oqoqo experiments launch`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-launch): `launchId`, `experimentId`, `status`, `runCount`, and `dashboardUrl`. Follow the launch with `oqoqo experiments watch`.

**Notes**

The launch uses the latest tasks, under the schedule's name, and doesn't move the next scheduled launch. It refuses with `experiment_schedule_run_active` while the schedule's last experiment still runs (see [Rules for every change](#rules-for-every-change)).

## oqoqo schedules delete

Delete a schedule. The experiments it launched stay.

```bash theme={null}
oqoqo schedules delete <schedule-id> --lock-version <n> [flags]
```

**Plugin (MCP) tool:** [`delete_schedule`](https://docs.oqoqo.ai/mcp-server/schedules#delete_schedule)

> [!WARNING]
>
> The schedule stops launching and is deleted. You can't undo it.

**Arguments**

| Argument | Description |
| - | - |
| `<schedule-id>` | Required. The `sch_` schedule ID. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--lock-version` | integer | | Required. The `lockVersion` from `oqoqo schedules get`. |
| `--yes` | boolean | `false` | Skip interactive confirmation. Required with `--output json` or outside a terminal. |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

```bash theme={null}
oqoqo schedules delete sch_c0a9f311 --lock-version 4 --yes --output json
```

**Result fields**

| Field | Description |
| - | - |
| `status` | `deleted`. |
| `scheduleId` | The deleted schedule's `sch_` ID. |

**Notes**

Deleting a schedule that is already deleted returns `schedule_not_found`.

## Schedule fields

`oqoqo schedules get`, `list`, `create`, `update`, `pause`, and `resume` return these fields. `oqoqo schedules preview` returns the cadence, run, and shortfall fields.

| Field | Description |
| - | - |
| `scheduleId`, `name` | The `sch_` ID and the name. |
| `status` | `active` or `paused`. |
| `needsAttention` | `true` when Oqoqo paused the schedule. The dashboard shows **Needs attention**. |
| `pauseReason` | Why Oqoqo paused it: a `code`, a `message`, and an `action` link that fixes it. |
| `cron`, `timeZone` | The cadence, and the IANA time zone that Oqoqo stores. |
| `cadenceDescription`, `timeZoneLabel` | The same in plain words, such as "Every weekday at 9:00 AM" and "Pacific Time (Los Angeles)". |
| `nextRunAt` | The next launch. `null` while paused. |
| `sourceExperiment` | The experiment it launches: `experimentId` and `label`. |
| `runsAs` | The person it runs as: `name` and `email`. |
| `runsPerLaunch` | The runs each launch uses. |
| `runsPer30Days` | The runs the next 30 days use, not a monthly average. `0` while paused, or when no launch falls in the next 30 days. |
| `shortfall` | When your runs fall short (next table). `null` while your runs cover the launches, or while the schedule is paused. |
| `lastResult` | What happened at the last scheduled launch: `outcome` (`launched`, `skipped`, or `failed`), a `code` and `message`, and `scheduledFor`. |
| `skippedInARow` | Launches skipped in a row because the last experiment was still running. After 3, the schedule's owners get a **Schedule skipping launches** notification. |
| `lastExperiment` | The last experiment it launched: `experimentId`, `label`, and `status`. |
| `lockVersion` | The version to pass as `--lock-version` on the next change. |
| `dashboardUrl` | The schedule's page in the dashboard. |

| `shortfall` field | Description |
| - | - |
| `at` | This schedule's first launch that your runs do not cover. |
| `runsShort` | The runs to add before that launch. |
| `availableRuns` | The runs you have now. |
| `launchesCovered` | The launches your runs cover. |
| `runsToAdd` | The runs that cover every scheduled launch until `until`. |
| `until` | The end of the period that `runsToAdd` covers. |
| `untilReset` | `true` when `until` is the next reset of your runs. |
| `message` | The shortfall in plain words. |
| `action` | A link to **Organization settings → Usage & billing**, where you [add runs](https://docs.oqoqo.ai/setup/billing.md). |

In [`oqoqo notifications list`](https://docs.oqoqo.ai/cli/billing-and-notifications#oqoqo-notifications-list), a schedule's paused, skipping, and short-of-runs notifications, and the problem notifications of the experiments it launched, carry its `scheduleId`. To read the runs or frictions of everything a schedule launched, pass `--schedule-id` to [`oqoqo runs list`](https://docs.oqoqo.ai/cli/runs#oqoqo-runs-list) or [`oqoqo frictions list`](https://docs.oqoqo.ai/cli/frictions#oqoqo-frictions-list).

## Related

> [card] [Schedules](https://docs.oqoqo.ai/experiments/schedules.md)
>
> How schedules launch, who they run as, and when they pause.

> [card] [Track results over time](https://docs.oqoqo.ai/guides/track-agents-over-time.md)
>
> Use a schedule to see how agents change from week to week.

> [card] [oqoqo experiments](https://docs.oqoqo.ai/cli/experiments.md)
>
> Watch the experiments a schedule launches.


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