List Agents

List Agents (Minimal)

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

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.xpander.ai/v1/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.xpander.ai/v1/agents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.xpander.ai/v1/agents"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.xpander.ai/v1/agents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5",
      "name": "Research Assistant",
      "description": "Searches the web and reports findings as JSON.",
      "icon": "🚀",
      "status": "ACTIVE",
      "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e",
      "deployment_type": "serverless",
      "model_provider": "anthropic",
      "model_name": "claude-sonnet-5",
      "type": "manager",
      "created_at": "2026-07-28T20:55:54.042725Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

GET

agents

List Agents (Minimal)

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

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.xpander.ai/v1/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.xpander.ai/v1/agents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.xpander.ai/v1/agents"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.xpander.ai/v1/agents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5",
      "name": "Research Assistant",
      "description": "Searches the web and reports findings as JSON.",
      "icon": "🚀",
      "status": "ACTIVE",
      "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e",
      "deployment_type": "serverless",
      "model_provider": "anthropic",
      "model_name": "claude-sonnet-5",
      "type": "manager",
      "created_at": "2026-07-28T20:55:54.042725Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

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.

This endpoint returns standard agents. Workflows (agents of type orchestration) are listed separately by List Workflows, so the count here can be lower than the total number of agents in your organization.

Which agents your key sees

The list depends on the API key you send. total counts only the agents that key sees.

API key	Agents it lists
The key marked Default in Access > API keys	Every agent in the organization, including agents other people keep personal
Any other platform API key	Every agent that is not personal, the personal agents of the person who owns the key, and the agents linked to the key. Only the linked agents are listed when this organization is not the owner’s active organization, the one they have open in xpander: the owner left it, or switched to another organization. A key limited to chosen agents lists only the chosen ones among these

A key is linked to an agent in these cases:

The agent was created with that key, through the API or the agent builder.
The agent was imported from a template: it is linked to one of the importing person’s API keys in the organization.
The key stepped down from Default: it stays linked to every agent the organization had at that moment.

A personal agent is one with access_scope set to personal (see Create Agent). Another person’s personal agent appears for a non-default key after its owner shares it with the organization, or when the key is linked to that agent. Each person’s Omni is personal. To pull every agent for an inventory, use the Default key.

Query Parameters

integer

default:1

Page number (starting from 1)

integer

default:20

Items per page (maximum 50)

Response

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

array

Array of agent objects

Show Agent Object

string

Unique identifier for the agent (UUID format)

string

Display name of the agent

string

Brief description of the agent’s purpose

string

Emoji icon representing the agent

string

Current deployment status: ACTIVE, INACTIVE

string

Organization UUID this agent belongs to

string

Deployment method: serverless or null

string

ISO timestamp of when the agent was created

string | null

UUID of the user who created the agent

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

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

object

High-level role, goal, and general instructions for the agent (nullable)

string

LLM provider: openai, anthropic, etc.

string

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

string

Agent framework used (e.g., external-harness)

string

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

string

Custom LLM base URL when the agent uses a proxied or self-hosted model endpoint (nullable)

boolean

Legacy. false, since changes save straight to the live agent

integer

Total number of agents across all pages

integer

Current page number

integer

Number of items per page

integer

Total number of pages available

Example Request

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

Example Response

{
  "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": "external-harness",
      "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 order of items is not guaranteed. Sort by created_at in your client if you need it
Use pagination to handle large result sets efficiently
Status values are: ACTIVE (deployed and ready), INACTIVE (not deployed)
See List Agents (Full Details) for complete agent configuration

Authorizations

x-api-key

string

header

required

API Key for authentication

Query Parameters

page

integer

default:1

Page number (starting from 1)

Required range: x >= 1

per_page

integer

default:20

Items per page (max 50)

Required range: 1 <= x <= 50

Response

Successful Response

items

MinimalAIAgentWithCreatedByDetails · object[]

required

Show child attributes

total

integer

required

page

integer

required

per_page

integer

required

total_pages

integer

required

Overview

REST API - Conversations

REST API - Agents

REST API - Tasks

Agent Workspace

REST API - Knowledge

REST API - Skills

REST API - Workflows

REST API - Custom Functions

REST API - Scheduled Tasks

REST API - Self-Schedules

REST API - Misc

Channels and webhooks

Which agents your key sees

Query Parameters

Response

Example Request

Example Response

Notes

Authorizations

Query Parameters

Response

​Which agents your key sees

​Query Parameters

​Response

​Example Request

​Example Response

​Notes

Authorizations

Query Parameters

Response

Which agents your key sees

Query Parameters

Response

Example Request

Example Response

Notes