Fetch Previously Created Agents

• View all your agents: Retrieve a complete list of all agent configurations associated with your API key
• Manage your agent library: Keep track of different agent configurations you’ve created for various use cases
• Reuse agent configurations: Access previously created agent settings to reuse them in new tasks or workflows
• Audit and organize: Review your agent inventory to understand what agents you have available and their configurations

​

Endpoint Information

• URL: /v1/agents/list
• Method: GET
• Authentication: Required (x-api-key header)
• Rate Limiting: Subject to tier-based rate limits

​

Response Format

• success: A boolean indicating whether the agent list was retrieved successfully
• count: An integer representing the total number of unique agent configurations in your account
• agents: An array of agent definition objects, each containing the complete configuration details of agents you’ve previously created, including:
  • Agent name and description
  • System prompts
  • Model configurations (model name, temperature, max_tokens, etc.)
  • Tool configurations
  • MCP integrations
  • Other agent-specific settings
• timestamp: An ISO 8601 UTC timestamp indicating when the list was generated

​

Use Cases

• Agent Discovery: Quickly see what agents you have available without needing to remember specific configuration details
• Configuration Reuse: Retrieve agent configurations to reuse in new API calls or workflows
• Inventory Management: Keep track of your agent library and identify agents that may need updates or cleanup
• Multi-Agent Workflows: List available agents to select and combine them in complex multi-agent architectures
• Development and Testing: Review agent configurations during development to ensure consistency across different environments

import json
import os
from typing import Any, Dict

import requests
from dotenv import load_dotenv

load_dotenv()

BASE_URL = "https://api.swarms.world"

HEADERS = {
    "x-api-key": os.getenv("SWARMS_API_KEY"),
    "Content-Type": "application/json",
}

def list_agents() -> Dict[str, Any]:
    """Retrieve all unique agent configurations"""
    try:
        response = requests.get(f"{BASE_URL}/v1/agents/list", headers=HEADERS)
        assert response.status_code == 200, f"Expected 200, got {response.status_code}: {response.text}"
        response_data = response.json()

        print(json.dumps(response_data, indent=4))
        count = response_data["count"]
        print(f"Number of agents: {count}")
        return response_data
    except Exception as e:
        print(str(e))
        return {}

if __name__ == "__main__":
    list_agents()

require('dotenv').config();

// const BASE_URL = "http://localhost:8080";
// const BASE_URL = "https://api.swarms.world";
const BASE_URL = "https://api.swarms.world";
const API_KEY = process.env.SWARMS_API_KEY;

async function listAgents() {
  const resp = await fetch(`${BASE_URL}/v1/agents/list`, {
    method: 'GET',
    headers: {
      'x-api-key': API_KEY,
      'Content-Type': 'application/json',
    },
  });
  if (!resp.ok) {
    console.error(`Error: ${resp.status} - ${await resp.text()}`);
    return;
  }
  const data = await resp.json();
  console.log(JSON.stringify(data, null, 2));
  console.log(`Number of agents: ${data.count}`);
}

listAgents().catch(console.error);

#!/usr/bin/env bash

# const BASE_URL="http://localhost:8080"
# const BASE_URL="https://api.swarms.world"
BASE_URL="https://api.swarms.world"

curl -X GET "${BASE_URL}/v1/agents/list" \
  -H "x-api-key: ${SWARMS_API_KEY}" \
  -H "Content-Type: application/json"