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

# Schedules

> Schedule a recipe to run once at a set time, or every hour, day, week or month.

A schedule runs a [recipe](https://docs.mediamonster.app/recipes.md) on the clock and files the results in the Vault. See [Run it on its own](https://docs.mediamonster.app/workbench.md#run-it-on-its-own) for what schedules do and what they cost.

![Automations page: Shorts from new episodes every Monday and Thursday at 09:00, Monday cover art every Monday at 08:30, and a finished one-off voiceover, each with an on/off switch](https://mintcdn.com/mediamonster/FNHLcHDdAKOFTzG0/images/screenshots/app-automations.png?fit=max\&auto=format\&n=FNHLcHDdAKOFTzG0\&q=85\&s=7db5f05f92c571e99c9214e5d17a6075)

Schedules made here show up on the Automations page in the app, with the ones started by a trigger.

![Shorts from new episodes, open: Clips then Add captions on new files in Late Bite, saved to Vault / Late Bite / Shorts, every Monday and Thursday at 09:00, with its six runs listed on the right](https://mintcdn.com/mediamonster/FNHLcHDdAKOFTzG0/images/screenshots/app-automation.png?fit=max\&auto=format\&n=FNHLcHDdAKOFTzG0\&q=85\&s=4ac0379e2ffb378399ffefeafa05eb38)

Open one and it is the workbench: the same fields as the API, from its steps and where results are saved to when it runs, with its runs beside them.

A key belongs to a person, so it works in the workspace that person is working in, with their role there. Owners, admins and members can create and change schedules. A viewer's key can list them. A guest's key lists none.

## List schedules

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl https://mediamonster.app/api/v1/schedules \
  -H "Authorization: Bearer mm_live_…"
```

Returns `{"schedules": [...]}`, oldest first. Each one has:

| Field | What it is |
| - | - |
| `id`, `name` | The schedule |
| `enabled` | Whether it runs. A paused or finished schedule is `false` |
| `paused` | `null`, or `{"at", "reason"}` when it stopped itself, for example because the workspace ran out of credits |
| `finished` | `true` once it has run as many times as it was asked to |
| `repeat` | `once`, `hourly`, `daily`, `weekly`, or `monthly` |
| `when` | How it reads, such as `"Weekdays at 09:00"` |
| `starts_at` | For `once`, when it runs. Otherwise nothing runs before it |
| `at_minute` | Minutes past local midnight. `hourly` reads only the minutes past the hour |
| `every_hours`, `weekdays`, `month_day` | The parts `hourly`, `weekly` and `monthly` read. `weekdays` counts from `0` for Sunday |
| `timezone` | The IANA zone its times are read in, such as `Europe/London` |
| `ends_after` | How many runs before it switches itself off, or `null` to keep going |
| `source` | `none`, `asset`, or `folder`: what each run starts from |
| `source_assets`, `source_folder` | `[{"id", "name"}]`, the files for `asset`, and the folder for `folder` |
| `source_asset` | The first of `source_assets`, for callers written for one file |
| `most_files` | For `folder`, the most files one run takes |
| `output_folder` | The Vault folder results are filed in |
| `next_run_at`, `last_run_at` | When it runs next, and when it last ran |
| `run_count` | How many times it has run on its clock |
| `recipe` | `{"id", "name", "missing", "version", "latest"}`. `id` is the saved recipe, or `null` for steps sent inline. `version` is the version it stays on, or `null` when it follows the recipe; `latest` is the recipe's newest |
| `steps` | The steps it runs now, in the shape `POST /api/v1/runs` takes them |
| `estimate` | `{"credits", "label"}`: what one run costs at least. A per-minute step is counted at one minute |
| `can_edit` | Whether this key's person may change it |

## Create a schedule

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl -X POST https://mediamonster.app/api/v1/schedules \
  -H "Authorization: Bearer mm_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Morning voiceover",
    "repeat": "weekly",
    "weekdays": [1, 2, 3, 4, 5],
    "at": "09:00",
    "timezone": "Europe/London",
    "steps": [{"tool": "text-to-voice", "prompt": "Good morning, here is today…"}],
    "output_folder": "Voiceovers"
  }'
```

| Field | Required | What it does |
| - | - | - |
| `name` | Yes | Up to 80 characters |
| `recipe_id` or `steps` | One of them | A recipe you saved on the Workbench, or steps written inline. `steps` takes the same shape as [`POST /api/v1/runs`](https://docs.mediamonster.app/api/runs) |
| `recipe_version` | No | With `recipe_id`: stay on this version, whatever the recipe is edited to. `null`, or left out on a new schedule, follows the recipe, so each run takes its latest steps. Another `recipe_id`, or `steps`, starts following again |
| `repeat` | No | `once`, `hourly`, `daily` (the default), `weekly`, or `monthly` |
| `starts_at` | For `once` | An ISO date and time in the future. For the others, nothing runs before it |
| `at` | No | `HH:MM`. Defaults to `09:00` |
| `every_hours` | No | For `hourly`: 1, 2, 3, 4, 6, 8, or 12. Counted from local midnight |
| `weekdays` | For `weekly` | Days from `0` (Sunday) to `6` (Saturday) |
| `month_day` | No | For `monthly`: 1 to 28 |
| `timezone` | No | An IANA zone. Defaults to `UTC` |
| `ends_after` | No | A number of runs, or `null` to keep going |
| `source` | No | `none` (the default), `asset`, or `folder` |
| `source_asset_ids` | For `asset` | Up to 50 Vault files. Each is run through the steps every time, one run each |
| `source_asset_id` | For `asset` | One Vault file, the same as a list of one |
| `source_folder` | For `folder` | Each run takes the files that landed there, or in a folder inside it, since the last run |
| `most_files` | No | For `folder`: 1 to 200. Defaults to 20 |
| `output_folder` | No | Where results are filed. Defaults to `Scheduled` |
| `input_values` | For inputs | A value for each of the steps' `{{inputs}}`, like `{"title": "Weekly roundup"}`. Every required one has to be here, unless the automation runs from a link, whose requests can send their own `inputs`. Alias: `inputs` |
| `most_upload_mb` | No | For an upload page: the largest file it takes, 1 to 100 MB. `null` is the plan's ceiling |
| `enabled` | No | Defaults to `true` |

Returns `201` with the schedule. It lists the steps' `inputs` and the `input_values` they run with.

A request to a webhook or upload page link (`POST /api/v1/triggers/{token}`) can send `inputs` of its own, as JSON or as form fields named `inputs[title]`. They win over the stored values for that request. Links take 120 posts from one network in 10 minutes.

The steps are checked by the same rules as a run, before anything is saved. They are refused with `400 bad_recipe` when a step can't follow the one above it, when a step that needs a prompt has none, when they include `route` or `send`, or when they can't start from `source`: `none` needs a first step that makes its own file, and `asset` and `folder` need one that takes a file.

A folder schedule starts counting from when it is created, not from the folder's older files.

## Get one schedule

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl https://mediamonster.app/api/v1/schedules/{id} \
  -H "Authorization: Bearer mm_live_…"
```

Returns the schedule with its 25 most recent `runs`, newest first:

| Field | What it is |
| - | - |
| `fired_at` | The time it ran for |
| `asset_id`, `file_name` | The file it ran on, for `asset` and `folder` |
| `status` | `queued`, `running`, `filing`, `complete`, `failed`, or `skipped` |
| `reason` | Why it was skipped or failed |
| `credits` | What it cost. While running, the estimate |
| `run_id` | The run, to read at [`GET /api/v1/runs/{id}`](https://docs.mediamonster.app/api/runs) |
| `outputs` | The files it made: `{"id", "url"}`. Read one at `GET /api/v1/assets/{id}` |

## Change a schedule, or run it now

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl -X POST https://mediamonster.app/api/v1/schedules/{id} \
  -H "Authorization: Bearer mm_live_…" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

Send only the fields that change. `{"enabled": true}` switches a paused or finished schedule back on, from its next time after now. `{"run_now": true}` runs it once now: its next time stays where it was, and the run doesn't count towards `ends_after`. The response then carries `fired`: `{"started", "skipped"}`.

## Delete a schedule

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl -X DELETE https://mediamonster.app/api/v1/schedules/{id} \
  -H "Authorization: Bearer mm_live_…"
```

Files it already made stay in the Vault.

## Errors

| Code | Status | When |
| - | - | - |
| `invalid_schedule` | 400 | A field is missing or the wrong shape, or it would never run. The message says which |
| `bad_recipe` | 400 | The steps can't run on a schedule, or from what it starts from |
| `not_allowed` | 403 | This key's person can't set up schedules, or can't add files to `output_folder` |
| `plan_required` | 403 | A step is on the paid plans |
| `recipe_not_found`, `asset_not_found`, `schedule_not_found` | 404 | No such recipe, file or schedule for this key |
| `recipe_version_not_found` | 404 | The recipe never had that `recipe_version` |
| `too_many_schedules` | 409 | The workspace has 50 schedules |

See [Errors](https://docs.mediamonster.app/api/errors.md) for the shape of an error body.


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