> ## 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.

# Schedules tools

> MCP tools for previewing, listing, creating, updating, pausing, resuming, and deleting recurring experiment schedules.

Schedule finished experiments to launch again on a cron cadence. See [Schedules](https://docs.oqoqo.ai/experiments/schedules.md) for permissions, pause causes, and limits.

* **Badges** are explained under [Approvals](https://docs.oqoqo.ai/mcp-server/overview.md#approvals).
* **`project_id`** is optional on most tools; without it, the server picks a project for that call only ([Projects](https://docs.oqoqo.ai/mcp-server/overview.md#projects)).
* **`expected_organization_id`** is an optional string on every write tool, omitted from parameter tables; pass `organization.id` from [`get_identity`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#get_identity) ([Organization check](https://docs.oqoqo.ai/mcp-server/overview.md#organization-check)).
* **`limit`** values above a tool's maximum are capped, not refused.

## Tools

### list\_schedules

**List schedules.** Lists a project's schedules, newest first, with `nextRunAt`, the person each runs as, the last result, and `needsAttention` with `pauseReason` when Oqoqo paused it.

Read-only · CLI: [`oqoqo schedules list`](https://docs.oqoqo.ai/cli/schedules#oqoqo-schedules-list)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `query` | string | No | Text to match, up to 200 characters. |
| `statuses` | array of `active`, `paused` | No | Only these statuses. |
| `experiment_id` | string | No | Only the schedules that launch this `exp_` experiment. |
| `launched_experiment_id` | string | No | Only the schedule that launched this `exp_` experiment. |
| `limit` | integer | No | Results per page, up to 200 (default 50). |
| `cursor` | string | No | The `nextCursor` from the previous page. Send it with the same filters. |

For a schedule's experiments, call `list_experiments` with `schedule_id`.

### get\_schedule

**Get a schedule.** Returns its cadence in plain words, `nextRunAt`, experiment, run use, last result, and the `lock_version` a change needs.

Read-only · CLI: [`oqoqo schedules get`](https://docs.oqoqo.ai/cli/schedules#oqoqo-schedules-get)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `schedule_id` | string | Yes | The `sch_` schedule. |

**Result fields**

`runsPerLaunch` is the runs each launch uses. `runsPer30Days` is the runs in the next 30 days, not a monthly average. It's 0 while the schedule is paused, or when no launch falls in the next 30 days.

### preview\_schedule

**Preview a schedule.** Shows what a new schedule or a change would do. Call it before `manage_schedule` and tell the person the runs it uses.

Read-only · CLI: [`oqoqo schedules preview`](https://docs.oqoqo.ai/cli/schedules#oqoqo-schedules-preview)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `experiment_id` | string | For a new schedule | The finished `exp_` experiment to run again. For a change, omit it to keep the current one. |
| `cron` | string | For a new schedule | Five cron fields in `time_zone`. The minute is 0, 15, 30, or 45, so the fastest cadence is hourly. `0 9 * * 1-5` is 9:00 AM on weekdays. |
| `time_zone` | string | For a new schedule | An IANA name such as `America/New_York`, or `UTC`; abbreviations such as `EST` are refused. Ask the person, because agents often run in UTC. |
| `schedule_id` | string | For a change | The `sch_` schedule. Send only what changes. |

**Result fields**

The preview has the cadence in plain words, the time zone it stores, the next 3 launches, `runsPerLaunch`, and `runsPer30Days`. A preview of a paused schedule counts it as resumed, and `schedule.status` says whether a changed schedule stays paused.

* `shortfall` is a warning, not a refusal. It's null while your runs cover the launches, or while the schedule is paused. Otherwise it gives `at` (the first uncovered launch), `runsShort`, `availableRuns`, `launchesCovered`, `runsToAdd` (to cover every launch until `until`), `until`, `untilReset` (true when `until` is your next run reset), a `message`, and an `action` linking Usage & billing.
* `blockers` lists everything that would stop a launch now, each with a `code`, `message`, and `action` with its fix link, so the person can fix them all at once. While it isn't empty, a create, a resume, or a change to the experiment, cron, or time zone refuses with `schedule_launch_blocked`. `blocker` (the first one) is for older CLI releases.

### manage\_schedule

**Create or change a schedule.** Creates, changes, pauses, or resumes a schedule. Each launch uses the project's tasks, treatments, and agents as they are then.

Changes data · You approve each call · CLI: [`oqoqo schedules create`](https://docs.oqoqo.ai/cli/schedules#oqoqo-schedules-create), [`oqoqo schedules update`](https://docs.oqoqo.ai/cli/schedules#oqoqo-schedules-update), [`oqoqo schedules pause`](https://docs.oqoqo.ai/cli/schedules#oqoqo-schedules-pause), [`oqoqo schedules resume`](https://docs.oqoqo.ai/cli/schedules#oqoqo-schedules-resume)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `action` | `create`, `update`, `pause`, `resume` | Yes | What to do. |
| `experiment_id` | string | With `create` | The finished `exp_` experiment to launch again. Optional with `update`. |
| `cron` | string | With `create` | Five cron fields, as in [`preview_schedule`](https://docs.oqoqo.ai/mcp-server/schedules#preview_schedule). Optional with `update`. |
| `time_zone` | string | With `create` | An IANA name, or `UTC`. Optional with `update`. |
| `name` | string | No | With `create` or `update`: the schedule name, 1 to 120 characters. |
| `schedule_id` | string | With `update`, `pause`, `resume` | The `sch_` schedule. |
| `lock_version` | integer | With `update`, `pause`, `resume` | From `get_schedule`. A stale value returns `schedule_changed`. |
| `attempt_id` | string | With `create` and `update` | An ID you choose, so that a retry doesn't repeat the change. It has 16 to 200 letters, digits, `_`, or `-`. |

* A create, a resume, or a change to the experiment, cron, or time zone checks the launch as you, and makes you the person the schedule runs as. If blocked, it refuses with `schedule_launch_blocked`, with `details.blockers` shaped as in [`preview_schedule`](https://docs.oqoqo.ai/mcp-server/schedules#preview_schedule); the message is the blocker's own, or a count when there are several.
* `update` changes only the fields you send. A schedule still named after its experiment takes the new experiment's name.
* Oqoqo pauses a schedule when a launch needs a fix, or after 3 scheduled launches in a row fail. A checked change clears the reason, but the schedule stays paused until you resume it.
* After the person fixes the cause, `resume` checks the launch and resumes. If something still blocks it, give the person every fix link in `details.blockers`, then resume again. Pause and resume are safe to repeat, and resume never launches at once.
* A create or resume past 50 active schedules in a project returns `schedule_limit_reached`.
* Reusing an `attempt_id` for a different schedule change returns `schedule_attempt_reused`. Missing schedules return `schedule_not_found`.
* To launch a schedule now, call `rerun_experiment` with `schedule_id`.

### delete\_schedule

**Delete a schedule.** Deletes a schedule. The experiments it launched stay.

Destructive · Irreversible · CLI: [`oqoqo schedules delete`](https://docs.oqoqo.ai/cli/schedules#oqoqo-schedules-delete)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `schedule_id` | string | Yes | The `sch_` schedule. |
| `lock_version` | integer | Yes | From `get_schedule`. A stale value returns `schedule_changed`. |

An already deleted schedule returns `schedule_not_found`.

## Related

> [card] [Experiments tools](https://docs.oqoqo.ai/mcp-server/experiments.md)
>
> Launch a schedule's experiment now with `rerun_experiment`.

> [card] [oqoqo schedules](https://docs.oqoqo.ai/cli/schedules.md)
>
> The matching CLI commands and flags.


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