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

# Scheduled tasks

> Give a coworker a cron or a one-off run, and fire it on demand to test it.

A scheduled task runs a coworker with no user message. Its body is the instruction the coworker receives when it fires. See [Automations](https://docs.rerun.build/agents/automations.md) for the concept.

## list\_schedules

Lists a coworker scheduled tasks in full: `slug`, `name`, `body`, `cron` or `runAt`, `timezone`, the connection and model of its own when it has one, enabled state and last run.

**agentId** `string` *required*

This is how you audit what an existing scheduled task actually does.

## upsert\_schedule

Creates a scheduled task, or updates it when `slug` is given.

**agentId** `string` *required*

**slug** `string`

Omit to create. Pass an existing slug to update.

**name** `string`

Required when creating. The slug is derived from it.

**body** `string`

Required when creating. The instruction sent to the coworker when the task fires, written as if you were talking to it.

**cron** `string`

Standard 5-field cron, for example `0 9 * * 1` for every Monday at 9. Required when creating unless you pass `runAt`.

**runAt** `string`

ISO date for a one-off run. The task disables itself after it fires.

**timezone** `string`

IANA timezone, for example `Europe/Paris`. Without it, the cron is read in the timezone of your machine.

**description** `string`

**enabled** `boolean`

**connectionId** `string`

Run this one on a given AI connection, by its id from [`list_ai_connections`](https://docs.rerun.build/api/tools/agents#list_ai_connections). Goes with `model`.

**model** `string | null`

Run this one on a model of its own. Omit it and it runs whatever its coworker runs. Pass `null` to go back to that.

> [!WARNING]
>
> Two things to know. The slug is derived from the name and is what `run_schedule_now` and `delete_schedule` address, so read it back from the response. And an update can change a cron but cannot clear it, nor turn a recurring task into a one-off: delete and recreate for that.

## run\_schedule\_now

Fires a scheduled task immediately, without waiting for its cron.

**agentId** `string` *required*

**slug** `string` *required*

It works on a disabled task, does not enable it, and does not touch its last-run date. That makes it safe for testing an instruction before putting the task live.

Returns a `runId`. Read the outcome with [`get_run`](https://docs.rerun.build/api/tools/runs#get-run).

## delete\_schedule

**agentId** `string` *required*

**slug** `string` *required*

**confirm** `boolean` *required*

Must be `true`.


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