# Tasks and schedules

A Task is a saved brief, not an execution. A schedule can create future work but does not supply an executor or bypass approvals. Read the current Task and Schedule before editing; disabling future occurrences does not cancel an existing Run.

> [API guide](https://swarm.services/guide/api.md) · [Documentation index](https://swarm.services/guide/llms.txt) · [Web reference](https://swarm.services/guide/api/reference/mcp-tasks-and-schedules)

[Read the Runs guide](https://swarm.services/guide/runs.md) for the workflow.

## List Tasks

`swarm_list_tasks`

Read one bounded page of Task briefs in a Space.

Required: none. Optional: space_id, limit, cursor, order.
Effect: read. Capability: `space.read`.

## Get Task

`swarm_get_task`

Read one Task brief.

Required: task_id. Optional: none.
Effect: read. Capability: `space.read`.

## Save Task

`swarm_create_task`

Save a planning brief in an approved Space. This does not launch execution.

Required: title, description, idempotency_key. Optional: space_id, run_requirements.
Effect: control. Capability: `space.operate`.

## Update Task

`swarm_update_task`

Edit a Task before its Runs execute.

Required: task_id, title, description, idempotency_key. Optional: run_requirements, expected_updated_at.
Effect: control. Capability: `space.operate`.

## Cancel Task

`swarm_cancel_task`

Cancel a Task and its pending Runs before leasing or execution.

Required: task_id, idempotency_key. Optional: reason.
Effect: control. Capability: `space.operate`.

## List Schedules

`swarm_list_schedules`

Read one bounded page of schedules in a Space.

Required: none. Optional: space_id, limit, cursor, order, active_only.
Effect: read. Capability: `space.read`.

## Get Schedule

`swarm_get_schedule`

Read one saved schedule. A saved schedule does not prove execution completed.

Required: policy_id. Optional: none.
Effect: read. Capability: `space.read`.

## Schedule Task

`swarm_create_schedule`

Create requested scheduled work. schedule.once uses run_at; schedule.interval uses start_at and interval_seconds (60 to 31536000). Timestamps require RFC3339 with timezone. Uses normal execution settings, credits and approvals; missed intervals coalesce.

Required: name, trigger_key, trigger_config, target_task_id, idempotency_key. Optional: space_id, execution_policy_id, core_id, run_requirements.
Effect: control. Capability: `space.operate`.

## Update Schedule

`swarm_update_schedule`

Replace the timing and Task of a schedule in its approved Space. Supply the complete configuration. Uses normal execution settings, credits and approvals.

Required: policy_id, name, trigger_key, trigger_config, target_task_id, idempotency_key. Optional: execution_policy_id, core_id, run_requirements.
Effect: control. Capability: `space.operate`.

## Stop Schedule

`swarm_disable_schedule`

Stop future occurrences. Existing Runs are unchanged.

Required: policy_id, idempotency_key. Optional: none.
Effect: control. Capability: `space.operate`.