> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarms.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch Previously Created Agents

> Retrieve all agents you have created via the API

The List Agents endpoint (`/v1/agents/list`) allows you to retrieve all agent configurations you have previously created through the Swarms API. This endpoint provides a comprehensive view of your agent inventory, including their names, descriptions, system prompts, model configurations, and other settings.

When you create agents using the Swarms API (via the `/v1/agent/completions` endpoint or other agent creation methods), each agent configuration is stored in your account. The List Agents endpoint enables you to:

* **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

The endpoint returns a JSON object containing:

* **`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

## 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

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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);
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    #!/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"
    ```
  </Tab>
</Tabs>

<Note>
  Responses include a `count` of agents and an array of agent definitions you previously created.
</Note>