---
updatedAt: 2026-07-31T12:37:05.000Z
---

# List all Agents

Retrieves a list of agents that belong to a specified tenant and match the filter criteria. Pagination, filtering, and sorting are supported. A maximum of 1000 records are returned.

**Required Entitlements** (at least one): tenantAdmin, readAgents, writeAgents, manageAgentStatus, agentOwner

**Examples**
- List all agents: `GET /Agents`
- Paginate results: `GET /Agents?startIndex=51&count=50`
- Filter by name: `GET /Agents?filter=displayName eq "MyAgent"`
- Filter by ID: `GET /Agents?filter=id eq "550e8400-e29b-41d4-a716-446655440000"`
- Filter by external ID: `GET /Agents?filter=externalId eq "ext-123"`
- Sort by name: `GET /Agents?sortBy=displayName&sortOrder=ascending`
- Combined: `GET /Agents?startIndex=1&count=25&filter=displayName eq "MyAgent"&sortBy=displayName&sortOrder=ascending`

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "version": "1.0.0",
    "description": "AI Agents",
    "title": "AI Agents"
  },
  "servers": [
    {
      "url": "https://{tenanturl}",
      "variables": {
        "tenanturl": {
          "default": "{tenant_url}",
          "description": "URL of your IBM Security Verify tenant"
        }
      }
    }
  ],
  "tags": [
    {
      "name": "Agent management",
      "description": "SCIM 2.0 compliant agent operations"
    }
  ],
  "paths": {
    "/v1.0/Agents": {
      "get": {
        "tags": [
          "Agent management"
        ],
        "summary": "List all Agents",
        "description": "Retrieves a list of agents that belong to a specified tenant and match the filter criteria. Pagination, filtering, and sorting are supported. A maximum of 1000 records are returned.\n\n**Required Entitlements** (at least one): tenantAdmin, readAgents, writeAgents, manageAgentStatus, agentOwner\n\n**Examples**\n- List all agents: `GET /Agents`\n- Paginate results: `GET /Agents?startIndex=51&count=50`\n- Filter by name: `GET /Agents?filter=displayName eq \"MyAgent\"`\n- Filter by ID: `GET /Agents?filter=id eq \"550e8400-e29b-41d4-a716-446655440000\"`\n- Filter by external ID: `GET /Agents?filter=externalId eq \"ext-123\"`\n- Sort by name: `GET /Agents?sortBy=displayName&sortOrder=ascending`\n- Combined: `GET /Agents?startIndex=1&count=25&filter=displayName eq \"MyAgent\"&sortBy=displayName&sortOrder=ascending`",
        "parameters": [
          {
            "name": "startIndex",
            "in": "query",
            "description": "A 1-based index that indicates the start position of the result set. A value less than 1 is interpreted as 1. If not specified, defaults to 1.",
            "schema": {
              "minimum": 1,
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "count",
            "in": "query",
            "description": "The number of agents to return per page. The range is 1 to 200. If not specified, the default is 50.",
            "schema": {
              "maximum": 200,
              "minimum": 1,
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "filter",
            "in": "query",
            "description": "The filter expression used to search agents. Supported attributes: displayName, id, externalId. Supported operator: eq.\n\nFor example, displayName eq \"MyAgent\".",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sortBy",
            "in": "query",
            "description": "The attribute used to sort the results. Supported values: displayName, id.",
            "schema": {
              "type": "string",
              "enum": [
                "displayName",
                "id"
              ]
            }
          },
          {
            "name": "sortOrder",
            "in": "query",
            "description": "The sort order when agents are returned. Use with sortBy.",
            "schema": {
              "type": "string",
              "default": "ascending",
              "enum": [
                "ascending",
                "descending"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of agents retrieved successfully",
            "content": {}
          },
          "400": {
            "description": "Bad Request - Invalid pagination (CSINH1100E-CSINH1103E), search (CSINH1200E-CSINH1202E), or sort (CSINH1203E-CSINH1204E) parameters",
            "content": {}
          },
          "401": {
            "description": "Unauthorized - Authentication required",
            "content": {}
          },
          "403": {
            "description": "Forbidden - Insufficient permissions (CSINH2501E)",
            "content": {}
          },
          "500": {
            "description": "Internal Server Error (CSINH1000E)",
            "content": {}
          }
        },
        "x-category": "AI Agents",
        "x-publicAPI": "true"
      }
    }
  },
  "x-original-swagger-version": "2.0",
  "x-explorer-enabled": false
}
```