List Agents (Full Details)

List Agents (Full)

curl --request GET \
  --url https://api.xpander.ai/v1/agents/full \
  --header 'x-api-key: <api-key>'

{
  "items": [
    {
      "name": "<string>",
      "id": "<string>",
      "description": "<string>",
      "icon": "<string>",
      "model_provider": "<string>",
      "model_name": "<string>",
      "instructions": {
        "role": [],
        "goal": [],
        "general": ""
      },
      "knowledge_base_ids": [],
      "source_node_types": [],
      "tools": [],
      "created_at": "2023-11-07T05:31:56Z",
      "created_by": "<string>",
      "created_by_details": {
        "id": "<string>",
        "name": "<string>",
        "email": "<string>"
      }
    }
  ],
  "total": 123,
  "page": 123,
  "per_page": 123,
  "total_pages": 123
}

GET

agents

full

List Agents (Full)

curl --request GET \
  --url https://api.xpander.ai/v1/agents/full \
  --header 'x-api-key: <api-key>'

{
  "items": [
    {
      "name": "<string>",
      "id": "<string>",
      "description": "<string>",
      "icon": "<string>",
      "model_provider": "<string>",
      "model_name": "<string>",
      "instructions": {
        "role": [],
        "goal": [],
        "general": ""
      },
      "knowledge_base_ids": [],
      "source_node_types": [],
      "tools": [],
      "created_at": "2023-11-07T05:31:56Z",
      "created_by": "<string>",
      "created_by_details": {
        "id": "<string>",
        "name": "<string>",
        "email": "<string>"
      }
    }
  ],
  "total": 123,
  "page": 123,
  "per_page": 123,
  "total_pages": 123
}

Retrieve a paginated list of AI agents. Each item is the simplified agent view — core configuration plus a flat tools array (see Get Agent for the per-item field shape, including the AgentTool object). Low-level graph, attached_tools, and oas are not included; manage tools via the Tools API.

Query Parameters

page

integer

default:1

Page number (starting from 1)

per_page

integer

default:20

Items per page (maximum 50)

Response

Returns a paginated list of agents with complete details:

items

array

Array of complete agent objects

Show Agent Object

string

Unique identifier for the agent (UUID format)

unique_name

string

URL-safe unique name for the agent

name

string

Display name of the agent

description

string

Detailed description of the agent’s purpose and capabilities

icon

string

Emoji icon representing the agent

status

string

Current deployment status: ACTIVE, INACTIVE

organization_id

string

Organization UUID this agent belongs to

deployment_type

string

Deployment method: serverless, container, or null

framework

string

Agent framework used (e.g., agno)

type

string

Agent type: manager, regular, a2a, curl, or orchestration

created_at

string

ISO timestamp of when the agent was created

created_by

string | null

UUID of the user who created the agent

created_by_details

object | null

Resolved creator details, one per agent item — no extra request needed. null when created_by is empty or the user cannot be resolved — null-check before reading sub-fields.

Show Created By Details

string

User UUID

name

string

Display name — first + last name. Falls back to email, then id, when the name is missing. Not guaranteed to be a real first/last name.

string

User email

instructions

object

Complete system instructions configuration with role, goal, and general fields

model_provider

string

LLM provider: openai, anthropic, etc.

model_name

string

Specific model version (e.g., gpt-4o, gpt-4.1)

tools

array

Array of tool configurations attached to this agent

knowledge_bases

array

Array of knowledge base IDs attached to this agent

graph

array

Visual graph representation of agent’s tool and MCP connections

access_scope

string

Access control scope: organizational, team, or private

total

integer

Total number of agents across all pages

page

integer

Current page number

per_page

integer

Number of items per page

total_pages

integer

Total number of pages available

Example Request

curl -X GET -H "x-api-key: <your-api-key>" \
  "https://api.xpander.ai/v1/agents/full?page=1&per_page=2"

Example Response

{
  "items": [
    {
      "id": "<agent-id>",
      "unique_name": "product-specialist",
      "name": "Product Specialist",
      "description": "Processes queries to provide comprehensive product information",
      "icon": "🚀",
      "status": "ACTIVE",
      "organization_id": "<org-id>",
      "deployment_type": "serverless",
      "framework": "agno",
      "type": "manager",
      "created_at": "2026-02-05T18:35:04.724091Z",
      "created_by": "<user-id>",
      "created_by_details": {
        "id": "<user-id>",
        "name": "Jane Doe",
        "email": "jane@acme.com"
      },
      "model_provider": "openai",
      "model_name": "gpt-4.1",
      "instructions": {
        "role": [
          "You are a product specialist assistant"
        ],
        "goal": [
          "Provide accurate product information to customers"
        ],
        "general": "Be helpful and professional"
      },
      "tools": [
        {
          "id": "search-products",
          "name": "Search Products",
          "method": "get",
          "path": "/products/search"
        }
      ],
      "knowledge_bases": [],
      "graph": [],
      "access_scope": "organizational"
    }
  ],
  "total": 41,
  "page": 1,
  "per_page": 2,
  "total_pages": 21
}

Notes

This endpoint returns complete agent configurations, which may be slower than the minimal list endpoint
Use the minimal list endpoint (GET /v1/agents) if you only need basic agent information
The response is automatically filtered based on your API key’s permissions
Large responses may take longer to retrieve due to nested configurations

List Agents (Full Details)

Query Parameters

Response

Example Request

Example Response

Notes

See Also

Authorizations

Query Parameters

Response

​Query Parameters

​Response

​Example Request

​Example Response

​Notes

​See Also

Authorizations

Query Parameters

Response

Query Parameters

Response

Example Request

Example Response

Notes

See Also