> ## Documentation Index
> Fetch the complete documentation index at: https://developers.agentx.so/llms.txt
> Use this file to discover all available pages before exploring further.

# List Agents

> List every agent the project knows about, with each one's monitoring profile

Returns the project's agent registry, sorted by name. An agent row exists for every distinct
agent the engine has seen: agents are **auto-registered** the first time a root trace arrives
under a new name, and can also be registered explicitly with
[Register Agent](/api-reference/tracked-agents/add). Use this list to find the agent ids that
monitoring profiles, patterns, and online-evaluator scopes key off.

<Note>
  There is no separate "tracked agents" list on the self-host engine - every registered agent's
  traces appear in Live Traces. This endpoint replaces the hosted platform's
  `/ingest/tracked-agents` surface.
</Note>

## Authentication

<ParamField header="x-api-key" type="string" required>
  Project API key.
</ParamField>

## Response

<ResponseField name="agents" type="array">
  Array of agent objects, sorted by name. Each has:

  | Field               | Type           | Description                                                                                                                                                                                                                                                                                                                                                                                                        |
  | ------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | `_id`               | string         | Agent ID - pass as `agentId` on trace ingest, monitoring profiles, and scope arrays                                                                                                                                                                                                                                                                                                                                |
  | `name`              | string         | Display name (two agents may deliberately share one; see [Register Agent](/api-reference/tracked-agents/add))                                                                                                                                                                                                                                                                                                      |
  | `kind`              | string         | Always `"agent"`                                                                                                                                                                                                                                                                                                                                                                                                   |
  | `agentType`         | string         | Always `"external"` on self-host (agents arrive via SDK/dashboard registration, never a native agent builder)                                                                                                                                                                                                                                                                                                      |
  | `monitoringAgentId` | string         | Same value as `_id`                                                                                                                                                                                                                                                                                                                                                                                                |
  | `monitoringProfile` | object \| null | The agent's monitoring profile, or `null` when none has been configured. Includes `_id`, `agentId`, `enabled`, `failureDetectionEnabled`, `infoDetectionEnabled`, `topicsEnabled`, `sampleRate`, `retentionDays`, `thresholdOverrides`, `channels`, `coverageMode`, `approvalPolicy`, timestamps, and hosted-compatibility constants (`workspaceId: "local"`, `billingMode: "credits"`, `pausedForCredits: false`) |
  | `createdAt`         | string         | ISO 8601 timestamp                                                                                                                                                                                                                                                                                                                                                                                                 |
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl http://localhost:4700/api/v1/agents \
    -H "x-api-key: agtx_local_0f3c9a17d2b84e6a5c01b9f4e7d8a2c6431b5f97a0e2d4c8"
  ```

  ```python Python SDK theme={null}
  agents = client.monitor.list_agents()
  for agent in agents:
      print(agent["_id"], agent["name"])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "agents": [
      {
        "_id": "aG5kR8sLp3WvX1nC7qZtB",
        "name": "customer-support-agent",
        "kind": "agent",
        "agentType": "external",
        "monitoringAgentId": "aG5kR8sLp3WvX1nC7qZtB",
        "monitoringProfile": null,
        "createdAt": "2026-08-27T10:30:00.000Z"
      }
    ]
  }
  ```
</ResponseExample>