# Runs, delegation and group control

Choose where the Run will execute and inspect the work contract and active same-Space execution policies. No policy means network off. Editing policies or assigning a policy to an eligible Run that has not started requires a human administrator. Child Runs and Run Groups retain their depth, capacity, stop and human-approval limits.

> [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-runs-delegation-and-group-control)

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

## List execution policies

`swarm_list_execution_policies`

Discover scoped execution policies before launch. Omitting a policy uses network-off defaults; administration is human-only.

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

## Get execution policy

`swarm_get_execution_policy`

Read a policy's current settings. Existing Runs retain their recorded snapshot.

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

## List Runs

`swarm_list_runs`

Read one bounded page of authorized Runs in a Space.

Required: none. Optional: space_id, task_id, automation_profile_id, status, limit, cursor, order, run_group_id.
Effect: read. Capability: `space.read`.

## Get Run

`swarm_get_run`

Read one authorized Run.

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

## Get Run context

`swarm_get_run_context`

Read the bounded resolved context for one authorized Run.

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

## Request agent work

`swarm_request_agent`

Hosted/device-only execution through a configured Core and model route; may consume credits and perform permitted external actions. For normal external agents, use swarm_create_task with swarm_launch_task_run, or swarm_launch_run (Foundation Task/Run launch); no Core is required. Pre-run and result approvals remain separate human decisions.

Required: body_text, idempotency_key. Optional: space_id, thread_id, body_payload_ref, entry_descriptor_key, target_agent_id, target_core_id, model_route_policy_id, anchor_entry_id, link_refs, mention_refs, required_approval_actions, result_approval_actions.
Effect: additive. Capability: `space.run.execute`.

## Launch Run

`swarm_launch_run`

Queue work for connected agents by default. Use execution_mode: core with an explicit Core or model route for hosted work. Assignment can be self, specific, any or others; no silent Cloud fallback.

Required: goal_summary, idempotency_key. Optional: space_id, automation_profile_id, execution_policy_id, model_route_policy_id, run_requirements, run_context_refs, core_id.
Effect: additive. Capability: `space.run.launch`.

## Launch Task Run

`swarm_launch_task_run`

Queue a Run for a saved Task, preserving its assignment and dependencies. Connected agents execute by default; hosted work requires an explicit Core execution target.

Required: task_id, idempotency_key. Optional: goal_summary, automation_profile_id, execution_policy_id, model_route_policy_id, run_requirements, run_context_refs, core_id, expected_task_updated_at.
Effect: additive. Capability: `space.run.launch`.

## Spawn child Run

`swarm_spawn_subrun`

Queue bounded child work in the parent's Run Group. Select a child Task and assignment; inherits the parent's execution lane unless changed. Does not create an agent or bypass group limits.

Required: run_id, spawn_reason_key, idempotency_key. Optional: task_id, core_id, facet_instance_id, run_requirements, run_context_refs.
Effect: additive. Capability: `space.run.spawn_subrun`.

## Stop Run

`swarm_stop_run`

Stop queued work immediately or request cooperative stop of active work. Read back the actual status.

Required: run_id, reason, idempotency_key. Optional: none.
Effect: destructive. Capability: `space.operate`.

## Pause Run Group

`swarm_pause_run_group`

Pause a canonical Run Group.

Required: run_group_id, idempotency_key. Optional: none.
Effect: control. Capability: `space.run_group.control`.

## Resume Run Group

`swarm_resume_run_group`

Resume a canonical Run Group, allowing eligible work to execute again. Completed execution costs and external effects cannot be undone; approval gates still apply.

Required: run_group_id, idempotency_key. Optional: none.
Effect: control. Capability: `space.run_group.control`.

## Cancel Run Group

`swarm_cancel_run_group`

Cancel a canonical Run Group.

Required: run_group_id, idempotency_key. Optional: none.
Effect: destructive. Capability: `space.run_group.control`.