# Read Your Fleet

> The list and agent operations on whisper.agents: the roster by kind, and every field returned for one address including counters and key state.

*Source: https://www.whisper.security/docs/control-plane/operations/list*

---
Two read operations. `list` returns the roster, `agent` returns one entry in full. Both need `dns:zone:read`.

## list

Returns what the account holds, one row per item.

```whisper-call
CALL whisper.agents({op: 'list', args: {kind: 'agents'}})
```

### Arguments

| Argument | Contract |
|---|---|
| `kind` | `agents` for principals, `identities` for addresses on your own key, `records` for the DNS entries behind them. |

### Returns

Columns `kind` and `item`. Each `item` carries `label`, `fqdn`, `address`, `agent`, `created` and `state`.

## agent

Returns the full record for one address.

```whisper-call
CALL whisper.agents({op: 'agent', args: {address: '2a04:2a01:b69a:6717:e3b0:51ff:3bf7:f478'}})
```

`agent` and `address` are interchangeable. A value containing a `:` is read as an address, anything else as an identifier, so either argument name accepts either form.

### Identity

| Column | Holds |
|---|---|
| `agent` | The agent identifier. |
| `address` | Its routable `/128`. |
| `fqdn` | Its canonical name. |
| `ptr` | Its reverse name. |
| `label` | The short name you gave it. |
| `state` | Whether the allocation stands. This is registry state, not liveness. |
| `allocated_at` | When the address was allocated. |
| `contact` | The contact published on its registry record. |
| `last_seen` | When the plane last recorded activity for it. |

### Counters

| Column | Holds |
|---|---|
| `dns_queries` | Lookups made through the resolver. |
| `dns_blocked` | Lookups policy refused. |
| `dns_nxdomain` | Lookups that resolved to nothing. |
| `packets` | Packets carried. |
| `bytes_up`, `bytes_down` | Bytes out and in. |
| `connections_active` | Connections open now. |
| `connections_total` | Connections opened so far. |

### Keys and publication

| Column | Holds |
|---|---|
| `identity_spki` | The public key the identity is pinned to. |
| `tlsa_digest` | The digest published in the DANE pin. |
| `sshfp_digest` | The digest published for SSH. |
| `key_source` | Where the key came from. |
| `key_binding` | How the key is bound to the address. |
| `publication` | What has been published in DNS for it. |

[Keys, signing and encryption](/docs/identity/keys) covers what each of those records is for.

### Nesting

| Column | Holds |
|---|---|
| `parent` | The identity this one egresses behind, when there is one. |
| `children` | The identities egressing behind this one. |
| `depth` | How far down the chain it sits. |
| `roam` | Whether it may move between parents. |

[Nested identities](/docs/identity/nested) explains what a chain means for policy.

## Errors

| Code | Status | Meaning |
|---|---|---|
| `BAD_ARGS` | 400 | `kind` is not one of the three values, or neither `agent` nor `address` was given. |
| `NOT_FOUND` | 404 | No such address or identifier under this account. |
| `RESULT_TOO_LARGE` | 413 | The roster does not fit in one answer. Read it by `kind`. |