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. Read the Runs guide 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_idactive_onlylimitcursororder
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_idtask_idautomation_profile_idstatuslimitcursororderrun_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_textidempotency_key
Optional: space_idthread_idbody_payload_refentry_descriptor_keytarget_agent_idtarget_core_idmodel_route_policy_idanchor_entry_idlink_refsmention_refsrequired_approval_actionsresult_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_summaryidempotency_key
Optional: space_idautomation_profile_idexecution_policy_idmodel_route_policy_idrun_requirementsrun_context_refscore_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_ididempotency_key
Optional: goal_summaryautomation_profile_idexecution_policy_idmodel_route_policy_idrun_requirementsrun_context_refscore_idexpected_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_idspawn_reason_keyidempotency_key
Optional: task_idcore_idfacet_instance_idrun_requirementsrun_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_idreasonidempotency_key
Optional: None
Effect: destructive
Capability: space.operate

Pause Run Group

swarm_pause_run_group

Pause a canonical Run Group.

Required: run_group_ididempotency_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_ididempotency_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_ididempotency_key
Optional: None
Effect: destructive
Capability: space.run_group.control