List Agents

Returns a paginated list of AI agents registered in the system. Supports filtering by platform, status, and risk level. Use this API to discover and monitor all agents across your tenant.

Before You Begin

Ensure you have a valid Tenant URL, Subdomain, and Bearer Token before calling this API. Refer to Agent Identity Security API Reference for setup instructions.

Request Structure


Endpoint	`/agents/`
Method	`GET`
Sample URL	`https://<tenant-host>/api/v1/agents/?sort_by=risk_score&sort_order=desc&status=active&platform=claude_code&risk_level=critical&skip=0&limit=1`

Headers

Table 1. Request Headers
Name	Description
`Authorization`	(Mandatory) Bearer token for authentication. Format: `Authorization: Bearer <token>` Type: String
`X-Tenant-Subdomain`	(Mandatory) Tenant subdomain for multi-tenant routing. Example: `acme` Type: String
`Accept`	(Optional) Response format. Use `application/json` Type: String

Query Parameters

Table 2. Query Parameters
Name	Description
`platform`	(Optional) Filter by agent platform. Accepted values: `claude_code`, `n8n`, `cursor` Type: String
`status`	(Optional) Filter by agent status. Accepted values: `active`, `inactive` Type: String
`risk_level`	(Optional) Filter by risk level. Accepted values: `critical`, `high`, `medium`, `low`. This parameter is repeatable to filter by multiple levels. Type: String
`sort_by`	(Optional) Field to sort results by. Accepted values: `risk_score`, `name`, `created_at`, `updated_at` Type: String
`sort_order`	(Optional) Sort direction. Accepted values: `asc`, `desc` Type: String
`skip`	(Optional) Number of records to skip for pagination. Default: `0` Type: Integer
`limit`	(Optional) Maximum number of records to return. Default: `50`. Max: `1000` Type: Integer

Response Structure

Table 3. Response Fields
Field	Description
`total`	Total number of agents matching the applied filters Type: Integer
`skip`	Number of records skipped Type: Integer
`limit`	Number of records returned in this response Type: Integer
`agents`	Array of agent objects Type: Array
`agents[].id`	Unique agent UUID Type: String (UUID)
`agents[].name`	Display name of the agent Type: String
`agents[].type`	Agent platform type (e.g., `claude_code`) Type: String
`agents[].status`	Current status: `active` or `inactive` Type: String
`agents[].risk_score`	Computed risk score (0–100) Type: Integer
`agents[].owner`	Owner display string with email Type: String
`agents[].created_at`	ISO 8601 timestamp when the agent was created Type: String
`agents[].updated_at`	ISO 8601 timestamp of the last update Type: String

Status Codes

Table 4. HTTP Status Codes
HTTP Code	Description
200 OK	Agents listed successfully.
401 Unauthorized	Missing or invalid Bearer token. Ensure a valid token is included in the `Authorization` header.
422 Unprocessable Entity	Invalid query parameter value (e.g., `limit` exceeds 1000).

Sample Response

{
  "total": 1,
  "skip": 0,
  "limit": 1,
  "agents": [
    {
      "id": "f73ece58-68de-41a6-add9-2c98ba8af8b8",
      "name": "Claude - AVXPLM216",
      "type": "claude_code",
      "status": "active",
      "risk_score": 85,
      "owner": "Naveen <[email protected]>",
      "created_at": "2026-09-08T02:29:43.811090Z",
      "updated_at": "2026-09-30T09:00:17.148219Z"
    }
  ]
}