Skip to content
Ishvana Ishvana Docs

List Swarms

GET
/api/agents/swarm/list

List all swarms (active and completed)

Returns comprehensive list of all swarms with their current status, including both currently active swarms and up to 10 recently completed swarms from history. Provides full details for each swarm including ID, status, type, creation time, task description, agent count, and progress.

@param swarm_engine: Injected swarm execution engine @returns SwarmListResponse with active_swarms, completed_swarms, and total_count @raises HTTPException: If listing swarms fails or swarm engine unavailable

Response includes:

  • active_swarms: Currently executing swarms with real-time progress
  • completed_swarms: Last 10 completed swarms from history
  • total_count: Combined count of active and returned completed swarms

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful Response

SwarmListResponse

Response model for listing swarms.

Provides a comprehensive view of active and completed swarms in the system, enabling monitoring of current swarm execution state and historical swarm completion tracking.

Fields:

  • active_swarms: Currently active swarms
  • completed_swarms: Recently completed swarms
  • total_count: Total number of swarms

Active Swarms: Swarms currently executing or pending execution. Ordered by priority and creation time for task queue visualization.

Completed Swarms: Recently finished swarms (both successful and failed). Limited to last N swarms to prevent excessive response size. Ordered by completion time (most recent first).

Usage: GET /api/swarm/list for swarm overview and monitoring.

JSON Example:

{
  "activeSwarms": [
    {
      "swarmId": "swarm_abc123",
      "status": "active",
      "swarmType": "code_analysis",
      "progress": 0.65
    }
  ],
  "completedSwarms": [
    {
      "swarmId": "swarm_def456",
      "status": "completed",
      "swarmType": "testing",
      "progress": 1.0
    }
  ],
  "totalCount": 15
}

Integration:

  • SwarmManagementInterface: Aggregates swarm data from execution engine
  • Monitoring Dashboard: Displays active and historical swarms
  • Analytics: Tracks swarm throughput and resource utilization
object
activeSwarms
required
Activeswarms

Currently active swarms

Array<object>
SwarmResponse

Response model for swarm operations.

Represents the current state and metadata of a multi-agent swarm, including execution status, progress tracking, and swarm composition details. Used for swarm creation responses, status queries, and monitoring updates.

Fields:

  • swarm_id: Unique swarm identifier
  • status: Current swarm status (pending, active, completed, failed, cancelled)
  • swarm_type: Type of swarm
  • created_at: Creation timestamp
  • task_description: Task description
  • agent_count: Number of agents in swarm
  • progress: Task completion progress (0.0-1.0)

Status Values:

  • pending: Swarm created but not yet started
  • active: Swarm currently executing
  • completed: Swarm finished successfully
  • failed: Swarm failed with error
  • cancelled: Swarm cancelled by user or system

Progress Range: 0.0 (0%) to 1.0 (100%), calculated based on completed sub-tasks

Usage: Returned from swarm creation, status queries, and list operations.

JSON Example:

{
  "swarmId": "swarm_abc123",
  "status": "active",
  "swarmType": "code_analysis",
  "createdAt": "2024-12-20T10:30:00Z",
  "taskDescription": "Analyze Python codebase for type safety issues",
  "agentCount": 5,
  "progress": 0.65
}

Integration:

  • SwarmExecutionEngine: Updates status and progress during execution
  • Monitoring Dashboard: Displays swarm state in real-time
  • Analytics System: Tracks swarm performance and completion rates
object
swarmId
required
Swarmid

Unique swarm identifier

string
status
required
Status

Current swarm status

string
swarmType
required
Swarmtype

Type of swarm

string
createdAt
required
Createdat

Creation timestamp

string
taskDescription
required
Taskdescription

Task description

string
agentCount
required
Agentcount

Number of agents in swarm

integer
progress
required
Progress

Task completion progress (0.0-1.0)

number
completedSwarms
required
Completedswarms

Recently completed swarms

Array<object>
SwarmResponse

Response model for swarm operations.

Represents the current state and metadata of a multi-agent swarm, including execution status, progress tracking, and swarm composition details. Used for swarm creation responses, status queries, and monitoring updates.

Fields:

  • swarm_id: Unique swarm identifier
  • status: Current swarm status (pending, active, completed, failed, cancelled)
  • swarm_type: Type of swarm
  • created_at: Creation timestamp
  • task_description: Task description
  • agent_count: Number of agents in swarm
  • progress: Task completion progress (0.0-1.0)

Status Values:

  • pending: Swarm created but not yet started
  • active: Swarm currently executing
  • completed: Swarm finished successfully
  • failed: Swarm failed with error
  • cancelled: Swarm cancelled by user or system

Progress Range: 0.0 (0%) to 1.0 (100%), calculated based on completed sub-tasks

Usage: Returned from swarm creation, status queries, and list operations.

JSON Example:

{
  "swarmId": "swarm_abc123",
  "status": "active",
  "swarmType": "code_analysis",
  "createdAt": "2024-12-20T10:30:00Z",
  "taskDescription": "Analyze Python codebase for type safety issues",
  "agentCount": 5,
  "progress": 0.65
}

Integration:

  • SwarmExecutionEngine: Updates status and progress during execution
  • Monitoring Dashboard: Displays swarm state in real-time
  • Analytics System: Tracks swarm performance and completion rates
object
swarmId
required
Swarmid

Unique swarm identifier

string
status
required
Status

Current swarm status

string
swarmType
required
Swarmtype

Type of swarm

string
createdAt
required
Createdat

Creation timestamp

string
taskDescription
required
Taskdescription

Task description

string
agentCount
required
Agentcount

Number of agents in swarm

integer
progress
required
Progress

Task completion progress (0.0-1.0)

number
totalCount
required
Totalcount

Total number of swarms

integer