# uip insights users

> Syntax and options for `uip insights users`, which reads the Insights users of the active tenant and their Insights role names.

`uip insights users` reads the tenant users visible to the current caller, along with their Insights role names. This is a read-only surface — there is no create, update, or delete verb.

:::important
Reading Insights users requires the **Insights Management View** permission in the active tenant. A session with no user identity (for example, one signed in with client credentials) cannot read this data at all and gets a 403.
:::

## Synopsis

```text
uip insights users list [--include-email] [-l <n>] [-o <n>]
```

This verb honors the [global options](./global-options.md) and the standard [exit codes](./exit-codes.md). It does not accept `-t, --tenant` — it uses the tenant selected during `uip login`.

## uip insights users list

List tenant users visible to the current caller, with their Insights role names.

### Options

| Flag | Description |
|---|---|
| `--include-email` | Include email addresses and the nested role IDs in the output. Off by default — the default view omits both. |
| `-l, --limit <number>` | Maximum rows to return. Defaults to `50`. |
| `-o, --offset <number>` | Rows to skip before returning results. |

Pagination is client-side: the backend returns the full unpaginated list, and the CLI slices it after fetching.

### Examples

```bash
uip insights users list

uip insights users list --include-email --limit 100
```

### Data shape — default view

```json
{
  "Code": "InsightsUsersList",
  "Data": [
    {
      "id": "b2c3d4e5-0000-0000-0000-000000000001",
      "name": "Jane Doe",
      "roles": [{ "name": "Viewer" }]
    }
  ],
  "Pagination": { "Returned": 1, "Limit": 50, "Offset": 0, "Total": 1, "HasMore": false },
  "Instructions": "Roles shown are the user's Insights roles in the active tenant, by name. A user's row is kept even when directory enrichment fails."
}
```

### Data shape — with `--include-email`

```json
{
  "Code": "InsightsUsersList",
  "Data": [
    {
      "id": "b2c3d4e5-0000-0000-0000-000000000001",
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "roles": [{ "id": 3, "name": "Viewer" }]
    }
  ],
  "Pagination": { "Returned": 1, "Limit": 50, "Offset": 0, "Total": 1, "HasMore": false }
}
```

A user's row is kept in the list even when directory enrichment (resolving display data) fails for that user — an incomplete row is not dropped.

## See also

- [Insights overview](./uip-insights.md)
- [alerts](./uip-insights-alerts.md), [alert-history](./uip-insights-alert-history.md) — other tenant-scoped read surfaces.