List Agents

GET/v1/agents

List agents owned by your organization, ordered most-recently-created first. Returns a page of Agent objects with an opaque cursor for the next page.

Query Parameters

Parameter	Type	Required	Description
limit	integer	❌	Page size. Default 20, max 100.
page	string	❌	Opaque cursor from a previous response's next_page.
include_archived	boolean	❌	Include archived agents. Default false.
created_at_gte	string	❌	Only agents created at or after this RFC 3339 time.
created_at_lte	string	❌	Only agents created at or before this RFC 3339 time.

Request Examples

Python

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-sb-YOUR_KEY",
    base_url="https://api.sandbase.ai"
)

page = client.beta.agents.list(limit=20)
for agent in page.data:
    print(f"{agent.id} v{agent.version} — {agent.name}")

cURL

curl "https://api.sandbase.ai/v1/agents?limit=20" \
  -H "Authorization: Bearer sk-sb-YOUR_KEY"

Response

{
  "data": [
    {
      "id": "agent_01HqR2k7...",
      "type": "agent",
      "version": 1,
      "name": "Research Assistant",
      "description": "A general-purpose research agent.",
      "model": { "id": "claude-sonnet-4", "speed": "standard" },
      "system": "You are a research assistant...",
      "tools": [
        {
          "type": "agent_toolset_20260401",
          "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } },
          "configs": [{ "name": "bash", "enabled": true, "permission_policy": { "type": "always_allow" } }]
        }
      ],
      "mcp_servers": [],
      "metadata": {},
      "archived_at": null,
      "created_at": "2026-05-29T10:00:00Z",
      "updated_at": "2026-05-29T10:00:00Z"
    }
  ],
  "next_page": "page_eyJjIjoiMjAyNi0wNS0yOVQxMDowMDowMFoiLCJpIjoiYWdlbnRfMDFIcVIyazcifQ"
}

Pagination

Results are ordered by created_at descending (ties broken by id). When more results exist, the response includes a next_page cursor; pass it back as the page parameter. When next_page is absent, you've reached the last page.

# Iterate through all pages
items = []
cursor = None
while True:
    page = client.beta.agents.list(limit=50, page=cursor)
    items.extend(page.data)
    cursor = getattr(page, "next_page", None)
    if not cursor:
        break

Errors

Status	Type	Description
400	invalid_request	Invalid page cursor or query parameters
401	authentication_error	Invalid or missing API key