# List the agents on your account

> Page: https://docs.plotwork.dev/api/get-user-agents. Index of every page: https://docs.plotwork.dev/llms.txt

The connections and the keys an agent has used on your own account, each with the agent it is, when it was last seen, and where it stands.

`GET /user/agents`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | List the agents on your account. |
| What does it take? | Nothing. |
| What does it return? | Status 200 with a body of type [`AgentList`](https://docs.plotwork.dev/api/schemas.md#agentlist). |
| What can go wrong? | `401` not signed in; `429` too many requests. Every failure uses the one error envelope. |

## What it does

The connections and the keys an agent has used on your own account, each with the agent it is, when it was last seen, and where it stands.

## Responses

| Status | Meaning | Body |
|---|---|---|
| 200 | The agents, the most recently used first. | [`AgentList`](https://docs.plotwork.dev/api/schemas.md#agentlist) |
| 401 | Not signed in. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 429 | Too many requests. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |

## Response body

A 200 answer has the type [`AgentList`](https://docs.plotwork.dev/api/schemas.md#agentlist).

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | `Agent[]` | yes |  |
| `items[].id` | `string` | yes |  |
| `items[].credential` | `"oauth" \| "key"` | yes | How it signs in: a browser sign-in (OAuth) or an API key in its settings. |
| `items[].name` | `string` | yes | The connection's registered agent name, or the key's name. |
| `items[].agent` | `object \| null` | yes | What the agent called itself (`clientInfo`) when it last opened an MCP session, or null when it never has. |
| `items[].agent.name` | `string` | yes |  |
| `items[].agent.version` | `string \| null` | yes |  |
| `items[].orgId` | `string \| null` | yes |  |
| `items[].createdAt` | `integer` | yes |  |
| `items[].lastUsedAt` | `integer \| null` | yes | Its last call, to within five minutes. |
| `items[].sessionAt` | `integer \| null` | yes | When it last opened an MCP session. |
| `items[].expiresAt` | `integer \| null` | yes |  |
| `items[].status` | `"live" \| "ready" \| "idle" \| "waiting" \| "blocked"` | yes | `live`: a call in the last 15 minutes. `ready`: in the last 30 days. `idle`: earlier. `waiting`: never used. `blocked`: its next call would be refused, and `blocked` says why. |
| `items[].blocked` | `"expired" \| "network" \| "two_factor" \| "membership" \| "policy" \| null` | yes |  |

## See also

| Doc | Why |
|---|---|
| [API reference](https://docs.plotwork.dev/api/reference.md) | Every endpoint, and the error envelope |
| [Schemas](https://docs.plotwork.dev/api/schemas.md) | Every request and response type |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The operations as callable tools |