Get Agent

Retrieves the full detail record for a single AI agent by its UUID. Returns all agent metadata, risk score, parent agent reference, owner information, and MCP/skill discovery status.

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.

You will also need the agent UUID of the agent you want to retrieve. Use the List Agents API to discover agent IDs.

Request Structure


Endpoint	`/agents/{agent_id}`
Method	`GET`
Sample URL	`https://<tenant-host>/api/v1/agents/f73ece58-68de-41a6-add9-2c98ba8af8b8`

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

Path Parameters

Table 2. Path Parameters
Name	Description
`agent_id`	(Mandatory) UUID of the agent to retrieve. Use the List Agents API to look up agent UUIDs. Type: String (UUID)

Response Structure

Table 3. Response Fields
Field	Description
`id`	Unique agent UUID Type: String (UUID)
`name`	Display name of the agent Type: String
`type`	Agent platform type (e.g., `claude_code`) Type: String
`status`	Current status: `active` or `inactive` Type: String
`risk_score`	Computed risk score (0–100) Type: Integer
`agent_metadata`	Platform-specific metadata object containing device details, username, and discovery status Type: Object
`agent_metadata.platform`	Operating system platform (e.g., `darwin`, `windows`) Type: String
`agent_metadata.username`	Username on the device running the agent Type: String
`agent_metadata.device_id`	Unique device identifier Type: String
`agent_metadata.device_name`	Human-readable device name Type: String
`agent_metadata.mcp_discovery_status`	Result of MCP server discovery: `success`, `failed`, or `pending` Type: String
`agent_metadata.skill_discovery_status`	Result of skill discovery: `success`, `truncated`, or `failed` Type: String
`agent_parent_id`	UUID of the parent or root agent Type: String (UUID)
`agent_parent`	Parent agent object containing `name`, `status`, and `id` Type: Object
`owner`	Owner display string with email Type: String
`created_at`	ISO 8601 timestamp when the agent was created Type: String
`updated_at`	ISO 8601 timestamp of the last update Type: String

Status Codes

Table 4. HTTP Status Codes
HTTP Code	Description
200 OK	Agent record returned successfully.
401 Unauthorized	Missing or invalid Bearer token. Ensure a valid token is included in the `Authorization` header.
404 Not Found	No agent found for the given UUID. Verify the `agent_id` is correct.
422 Unprocessable Entity	`agent_id` is not a valid UUID format.

Sample Response

{
  "id": "f73ece58-68de-41a6-add9-2c98ba8af8b8",
  "name": "Claude - AVXPLM216",
  "type": "claude_code",
  "status": "active",
  "risk_score": 85,
  "agent_metadata": {
    "platform": "darwin",
    "username": "Naveen",
    "device_id": "C9DMC4PXV6",
    "device_name": "AVXPLM216",
    "mcp_discovery_status": "success",
    "skill_discovery_status": "truncated"
  },
  "agent_parent_id": "597fe032-1399-47fc-870f-bb1b557ad2f1",
  "owner": "Naveen <[email protected]>",
  "created_at": "2026-09-08T02:29:43.811090Z",
  "updated_at": "2026-09-30T09:00:17.148219Z"
}