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

# List Agents

> Retrieve a paginated list of agents with core metadata. The response may include additional summary fields beyond ID, name, and status.

Retrieve a paginated list of agents for browsing and selection. Although this is the lighter-weight listing endpoint, the payload typically includes core deployment and model metadata and may include additional summary fields such as instructions or compatibility flags.

## Query Parameters

<ParamField query="page" type="integer" default={1}>
  Page number (starting from 1)
</ParamField>

<ParamField query="per_page" type="integer" default={20}>
  Items per page (maximum 50)
</ParamField>

## Response

Returns a paginated list of agent summaries. Treat unknown fields as forward-compatible metadata.

<ResponseField name="items" type="array">
  Array of agent objects

  <Expandable title="Agent Object">
    <ResponseField name="id" type="string">
      Unique identifier for the agent (UUID format)
    </ResponseField>

    <ResponseField name="name" type="string">
      Display name of the agent
    </ResponseField>

    <ResponseField name="description" type="string">
      Brief description of the agent's purpose
    </ResponseField>

    <ResponseField name="icon" type="string">
      Emoji icon representing the agent
    </ResponseField>

    <ResponseField name="status" type="string">
      Current deployment status: ACTIVE, INACTIVE
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization UUID this agent belongs to
    </ResponseField>

    <ResponseField name="deployment_type" type="string">
      Deployment method: serverless, container, or null
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO timestamp of when the agent was created
    </ResponseField>

    <ResponseField name="created_by" type="string | null">
      UUID of the user who created the agent
    </ResponseField>

    <ResponseField name="created_by_details" type="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.

      <Expandable title="Created By Details">
        <ResponseField name="id" type="string">
          User UUID
        </ResponseField>

        <ResponseField name="name" type="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.
        </ResponseField>

        <ResponseField name="email" type="string">
          User email
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="instructions" type="object">
      High-level role, goal, and general instructions for the agent (nullable)
    </ResponseField>

    <ResponseField name="model_provider" type="string">
      LLM provider: openai, anthropic, etc.
    </ResponseField>

    <ResponseField name="model_name" type="string">
      Specific model version (e.g., gpt-4o, gpt-4.1)
    </ResponseField>

    <ResponseField name="framework" type="string">
      Agent framework used (e.g., agno)
    </ResponseField>

    <ResponseField name="type" type="string">
      Agent type: `manager`, `regular`, `a2a`, `curl`, or `orchestration`
    </ResponseField>

    <ResponseField name="llm_api_base" type="string">
      Custom LLM base URL when the agent uses a proxied or self-hosted model endpoint (nullable)
    </ResponseField>

    <ResponseField name="has_pending_changes" type="boolean">
      Whether the agent has unpublished configuration changes
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of agents across all pages
</ResponseField>

<ResponseField name="page" type="integer">
  Current page number
</ResponseField>

<ResponseField name="per_page" type="integer">
  Number of items per page
</ResponseField>

<ResponseField name="total_pages" type="integer">
  Total number of pages available
</ResponseField>

## Example Request

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

## Example Response

```json theme={"dark"}
{
  "items": [
    {
      "id": "<agent-id>",
      "name": "Product Specialist",
      "description": "Processes queries to provide comprehensive product information",
      "icon": "🚀",
      "status": "ACTIVE",
      "organization_id": "<org-id>",
      "deployment_type": "serverless",
      "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"
      },
      "instructions": {
        "role": [
          "Answer product questions clearly and accurately"
        ],
        "goal": [
          "Help users find the right product quickly"
        ],
        "general": "I am a product specialist focused on concise, accurate answers."
      },
      "model_provider": "openai",
      "model_name": "gpt-5.2",
      "framework": "agno",
      "type": "manager",
      "llm_api_base": null,
      "has_pending_changes": false
    }
  ],
  "total": 12,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}
```

## Notes

* `/v1/agents` is the lighter-weight listing endpoint, but the response includes more than just `id`, `name`, and `status`
* Additional fields may appear over time; client code should ignore unknown keys
* The `items` array is sorted by creation date (newest first)
* Use pagination to handle large result sets efficiently
* Status values are: `ACTIVE` (deployed and ready), `INACTIVE` (not deployed)
* See [List Agents (Full Details)](/api-reference/v1/agents/list-agents-full) for complete agent configuration


## OpenAPI

````yaml GET /v1/agents
openapi: 3.1.0
info:
  title: xpander.ai API Service
  description: |2-

        The xpander.ai API Service provides a unified REST API for managing AI agents,
        executing tasks, managing knowledge bases, and integrating with external systems.
        
        Features:
        - Agent Management: Create, update, deploy, and delete AI agents
        - Task Execution: Invoke agents with support for sync, async, and streaming modes
        - Knowledge Bases: Manage knowledge bases and documents for RAG workflows
        - Tools: Discover, connect, and attach tools (connectors, custom functions, MCP servers, sub-agents, workflows) to agents and workflows
        - MCP Integration: Model Context Protocol support for standardized AI interactions
        
        Authentication: All endpoints require authentication via either an API key (`x-api-key`) or an OAuth2 JWT (`Authorization: Bearer <jwt>`).
        
  version: '0.001'
servers:
  - url: https://api.xpander.ai
security: []
paths:
  /v1/agents:
    get:
      tags:
        - API v1
        - Agents
        - Agents CRUD
      summary: List Agents (Minimal)
      description: >-
        Retrieve a paginated list of AI agents with minimal information (ID,
        name, status)
      operationId: List_agents__minimal__v1_agents_get
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            description: Page number (starting from 1)
            default: 1
            title: Page
          description: Page number (starting from 1)
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            maximum: 50
            minimum: 1
            description: Items per page (max 50)
            default: 20
            title: Per Page
          description: Items per page (max 50)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/PaginatedResponse_MinimalAIAgentWithCreatedByDetails_
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    PaginatedResponse_MinimalAIAgentWithCreatedByDetails_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/MinimalAIAgentWithCreatedByDetails'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
        per_page:
          type: integer
          title: Per Page
        total_pages:
          type: integer
          title: Total Pages
      type: object
      required:
        - items
        - total
        - page
        - per_page
        - total_pages
      title: PaginatedResponse[MinimalAIAgentWithCreatedByDetails]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MinimalAIAgentWithCreatedByDetails:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        icon:
          anyOf:
            - type: string
            - type: 'null'
          title: Icon
        status:
          anyOf:
            - $ref: '#/components/schemas/AgentStatus'
            - type: 'null'
        organization_id:
          type: string
          title: Organization Id
        deployment_type:
          anyOf:
            - $ref: '#/components/schemas/AIAgentDeploymentType'
            - type: 'null'
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
        instructions:
          anyOf:
            - $ref: '#/components/schemas/AIAgentInstructions'
            - type: 'null'
        model_provider:
          anyOf:
            - $ref: '#/components/schemas/LLMModelProvider'
            - type: 'null'
        llm_api_base:
          anyOf:
            - type: string
            - type: 'null'
          title: Llm Api Base
        model_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Name
        framework:
          anyOf:
            - type: string
            - type: 'null'
          title: Framework
        using_nemo:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Using Nemo
        is_coordinate_mode:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Coordinate Mode
        has_pending_changes:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Has Pending Changes
        use_oidc_pre_auth:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Use Oidc Pre Auth
          default: false
        pre_auth_audiences:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Pre Auth Audiences
          default: []
        use_oidc_pre_auth_token_for_llm:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Use Oidc Pre Auth Token For Llm
          default: false
        oidc_pre_auth_token_llm_audience:
          anyOf:
            - type: string
            - type: 'null'
          title: Oidc Pre Auth Token Llm Audience
        oidc_pre_auth_token_mcp_audience:
          anyOf:
            - type: string
            - type: 'null'
          title: Oidc Pre Auth Token Mcp Audience
        type:
          anyOf:
            - $ref: '#/components/schemas/AgentType'
            - type: 'null'
        created_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Created By
        created_by_details:
          anyOf:
            - $ref: '#/components/schemas/CreatedByDetails'
            - type: 'null'
      type: object
      required:
        - name
        - organization_id
        - type
      title: MinimalAIAgentWithCreatedByDetails
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    AgentStatus:
      type: string
      enum:
        - DRAFT
        - ACTIVE
        - INACTIVE
      title: AgentStatus
      description: |-
        Enumeration of possible agent statuses.

        Attributes:
            DRAFT: Agent is in a draft state.
            ACTIVE: Agent is active and operational.
            INACTIVE: Agent is inactive and not operational.
    AIAgentDeploymentType:
      type: string
      enum:
        - serverless
        - container
      title: AIAgentDeploymentType
    AIAgentInstructions:
      properties:
        role:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role
          default: []
        goal:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Goal
          default: []
        general:
          anyOf:
            - type: string
            - type: 'null'
          title: General
          default: ''
      type: object
      title: AIAgentInstructions
    LLMModelProvider:
      type: string
      enum:
        - openai
        - nim
        - amazon_bedrock
        - azure_ai_foundary
        - huggingFace
        - friendlyAI
        - anthropic
        - gemini
        - fireworks
        - google_ai_studio
        - helicone
        - bytedance
        - tzafon_lightcone
        - open_router
        - nebius
        - cloudflare_ai_gw
      title: LLMModelProvider
    AgentType:
      type: string
      enum:
        - manager
        - regular
        - a2a
        - curl
        - orchestration
      title: AgentType
      description: |-
        Enumeration of the agent types.

        Attributes:
            Manager: marks the agent as a Managing agent.
            Regular: marks the agent as a regular agent.
            A2A: marks the agent as an external agent used via A2A protocol.
            Curl: marks the agent as an external agent used via a CURL.
            Orchestration: marks the agent as an Orchestration object.
    CreatedByDetails:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        email:
          type: string
          title: Email
      type: object
      required:
        - id
        - name
        - email
      title: CreatedByDetails
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: API Key for authentication
      in: header
      name: x-api-key

````