> Source: https://wexa.ai/docs/agents/list-agents

# list-agents

List the agents in this project, the same set the console's Agents page shows, one row per agent. Needs the `fabric:orchestrate.read` grant.

**List agents**

**Wexa MCP server**

```bash
curl -sS -X POST https://fabric.wexa.ai/mcp/$FABRIC_PROJECT_ID \
  -H "authorization: Bearer $FABRIC_API_KEY" \
  -H "Mcp-Session-Id: $MCP_SESSION_ID" \
  -H "content-type: application/json" -H "accept: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list-agents","arguments":{"limit":5}}}'
```

```json
{
  "content": [
    {
      "type": "text",
      "text": "{\"lifecycle_id\":\"qlc_000174\",\"result\":{\"agents\":[{\"agent_id\":\"6ab1945e7566f41b5c28e303.6ab1945e83ff5845d7db96bc\",\"name\":\"docs-fixture-agent\",\"role\":\"tester\",\"model\":\"system_model\"}],\"limit\":5,\"page\":1}}"
    }
  ],
  "isError": false
}
```

**REST API**

```bash
curl -sS https://fabric.wexa.ai/v1/list-agents \
  -H "authorization: Bearer $FABRIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"limit":5}'
```

```json
{
  "lifecycle_id": "qlc_000174",
  "result": {
    "agents": [
      {
        "agent_id": "6ab1945e7566f41b5c28e303.6ab1945e83ff5845d7db96bc",
        "name": "docs-fixture-agent",
        "role": "tester",
        "model": "system_model"
      }
    ],
    "limit": 5,
    "page": 1
  }
}
```

**TypeScript SDK**

```ts
import { Fabric } from '@wexa-fabric/sdk'

const fabric = new Fabric()
const result = await fabric.listAgents({
  limit: 5
})
```

```ts
// result is the payload itself, with no `.result` to read
{
  agents: [
    {
      agent_id: '6ab1945e7566f41b5c28e303.6ab1945e83ff5845d7db96bc',
      name: 'docs-fixture-agent',
      role: 'tester',
      model: 'system_model'
    }
  ],
  limit: 5,
  page: 1
}
```

**Python SDK**

```python
from wexa import Fabric

fabric = Fabric()
out = fabric.list_agents(limit=5)
```

```python
# out is the result, already unwrapped
{
    "agents": [
        {
            "agent_id": "6ab1945e7566f41b5c28e303.6ab1945e83ff5845d7db96bc",
            "name": "docs-fixture-agent",
            "role": "tester",
            "model": "system_model"
        }
    ],
    "limit": 5,
    "page": 1
}
```

## Parameters

| Parameter | Type | Required | Notes |
| --- | --- | --- | --- |
| `limit` | integer | Optional | Rows per page (default 20). |
| `page` | integer | Optional | 1-based page number, at least 1 (default 1). |
| `search` | string | Optional | Narrow the list by name. |

**Show full response**

A real response, captured from a live call to `list-agents`:

**Result of list-agents**

**REST API**

```json
{
  "lifecycle_id": "qlc_000174",
  "result": {
    "agents": [
      {
        "agent_id": "6ab1945e7566f41b5c28e303.6ab1945e83ff5845d7db96bc",
        "description": "A stable agent the documentation cites.",
        "is_promoted": false,
        "model": "system_model",
        "name": "docs-fixture-agent",
        "role": "tester"
      }
    ],
    "limit": 5,
    "page": 1
  }
}
```

**Wexa MCP server**

```json
{
  "content": [
    {
      "type": "text",
      "text": "{\"lifecycle_id\":\"qlc_000174\",\"result\":{\"agents\":[{\"agent_id\":\"6ab1945e7566f41b5c28e303.6ab1945e83ff5845d7db96bc\",\"description\":\"A stable agent the documentation cites.\",\"is_promoted\":false,\"model\":\"system_model\",\"name\":\"docs-fixture-agent\",\"role\":\"tester\"}],\"limit\":5,\"page\":1}}"
    }
  ],
  "isError": false
}
```

**TypeScript SDK**

```ts
// the object you get back IS the result — there is no `.result` to read
{
  agents: [
    {
      agent_id: '6ab1945e7566f41b5c28e303.6ab1945e83ff5845d7db96bc',
      description: 'A stable agent the documentation cites.',
      is_promoted: false,
      model: 'system_model',
      name: 'docs-fixture-agent',
      role: 'tester'
    }
  ],
  limit: 5,
  page: 1
}

// The TS SDK names these camelCase — lifecycleId, traceId — where Python uses
// lifecycle_id and trace_id. Both are non-enumerable: readable, but omitted by
// Object.keys() and JSON.stringify(). `result.lifecycleId` here is undefined.
result.lifecycleId // 'qlc_000174'
```

**Python SDK**

```python
# a dict subclass; `result` is already unwrapped
{
 "agents": [
  {
   "agent_id": "6ab1945e7566f41b5c28e303.6ab1945e83ff5845d7db96bc",
   "description": "A stable agent the documentation cites.",
   "is_promoted": False,
   "model": "system_model",
   "name": "docs-fixture-agent",
   "role": "tester"
  }
 ],
 "limit": 5,
 "page": 1
}

out.lifecycle_id  # 'qlc_000174' — an attribute, not a key
```

**More details**

Every argument is optional: `list-agents` answers a bare call. Multi-agent process flows are excluded; list them with [get-process-flow](/docs/automation/get-process-flow). Each row's `agent_id` is accepted unchanged by `get-agent`, `update-agent`, `delete-agent` and `run-agent`.

Every tool call works the same way: [How every tool call works](/docs/sdks-and-apis/how-every-tool-call-works).