List agents | Alephant API Documentation

curl -G https:https://localhost:8080/api/v1/agents \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.exampletoken1234567890" \
     -H "X-Workspace-Id: a3f1c9d2-4b7e-4f3a-9d2e-8b7c6a5d4e3f" \
     -H "Content-Type: application/json" \
     -d page=1 \
     -d pageSize=20 \
     -d status=active \
     -d departmentId=d2f9a1b4-7c3e-4d8f-9a2b-1c3d4e5f6a7b \
     -d environment=production \
     --data-urlencode "search=customer support"

{
  "data": [
    {
      "id": "e7a1c2d3-4b5f-6789-0abc-def123456789",
      "name": "Support Agent Alpha",
      "status": "active",
      "departmentId": "d2f9a1b4-7c3e-4d8f-9a2b-1c3d4e5f6a7b",
      "environment": "production",
      "description": "Handles customer support tickets for North America region.",
      "periodCost": 125.75,
      "periodRequests": 3400,
      "periodTokens": 150000,
      "meta": {
        "costBreakdown": {
          "apiCalls": 100.5,
          "storage": 15.25,
          "compute": 10
        }
      }
    },
    {
      "id": "f8b2d3e4-5c6f-7890-1bcd-ef234567890a",
      "name": "Development Agent Beta",
      "status": "active",
      "departmentId": "d2f9a1b4-7c3e-4d8f-9a2b-1c3d4e5f6a7b",
      "environment": "development",
      "description": "Agent used for internal development and testing.",
      "periodCost": 75.4,
      "periodRequests": 2100,
      "periodTokens": 90000,
      "meta": {
        "costBreakdown": {
          "apiCalls": 60,
          "storage": 10.4,
          "compute": 5
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalPages": 5,
      "totalItems": 85
    }
  }
}

List agents with optional filters (status, departmentId, environment, search). When Collector is configured, period cost/requests/tokens and meta.costBreakdown are merged from GET /v1/analytics/agents/cost-breakdown (Collector default window). Owner, admin, viewer.

Query parameters

pageintegerOptionalDefaults to 1

Page number

pageSizeintegerOptionalDefaults to 20

Items per page

statusstringOptional

active, inactive, archived

departmentIdstringOptional

Department UUID

environmentstringOptional

production, development, staging

searchstringOptional

Search name/description

Response

data: list, meta: pagination

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

Headers

Query parameters

Response

Errors