uip insights groups

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

uip insights groups reads the tenant groups 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 groups 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

uip insights groups list [--include-email] [-l <n>] [-o <n>]
uip insights groups get <group-id> [--include-email]

Both verbs honor the global options and the standard exit codes. Neither accepts -t, --tenant — they use the tenant selected during uip login.

uip insights groups list

List tenant groups visible to the current caller, with their Insights role names. Each row is resolved through the directory — one cached call per group, in sequence — so a large tenant's first (cold-cache) list can be slower than a users list of similar size.

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

uip insights groups list

uip insights groups list --include-email --limit 100

Data shape — default view

{
  "Code": "InsightsGroupsList",
  "Data": [
    { "id": "d1e2f3a4-0000-0000-0000-000000000001", "name": "Automation Users", "roles": [{ "name": "Viewer" }] }
  ],
  "Pagination": { "Returned": 1, "Limit": 50, "Offset": 0, "Total": 1, "HasMore": false },
  "Instructions": "Roles shown are the group's Insights roles in the active tenant, by name; 'uip insights roles list' maps a role name to its role GUID and back. Directory filtering can omit unresolved groups, so a missing row is not proof the stored group does not exist. Listing groups resolves each row through the directory, one cached call per group in sequence. 'uip insights groups get' returns the same fields as a row here and can persist refreshed directory name and email fields for the group, so read the row here when it is enough."
}

Data shape — with --include-email

{
  "Code": "InsightsGroupsList",
  "Data": [
    {
      "id": "d1e2f3a4-0000-0000-0000-000000000001",
      "name": "Automation Users",
      "email": "[e-mail]",
      "roles": [{ "id": "c1d2e3f4-0000-0000-0000-000000000001", "name": "Viewer" }]
    }
  ],
  "Pagination": { "Returned": 1, "Limit": 50, "Offset": 0, "Total": 1, "HasMore": false }
}

Directory filtering can drop rows. A group the backend's directory lookup can't resolve is omitted from the list entirely — a missing group is not proof it doesn't exist; groups get may still resolve it directly. On an empty list, the standing note above is dropped since nothing was withheld from zero rows, but the directory-resolution caveat and the per-group cost note still apply.

uip insights groups get

Get one Insights group by its GUID. Unlike list, this can persist refreshed directory name and email fields for the group as a side effect — it's read-shaped but not a pure read.

Arguments

Name	Required	Purpose
<group-id>	yes	Group GUID. Must be a real GUID — a malformed value fails client-side with Run 'uip insights groups list' to find a group ID. before any network call.

Options

Flag	Description
--include-email	Include email addresses and the nested role IDs in the output. Off by default.

Example

uip insights groups get d1e2f3a4-0000-0000-0000-000000000001

Data shape (--output json)

{
  "Code": "InsightsGroupGet",
  "Data": { "id": "d1e2f3a4-0000-0000-0000-000000000001", "name": "Automation Users", "roles": [{ "name": "Viewer" }] }
}

With --include-email, the same shape gains email and the nested roles[].id, same as the list view.

Group <id> was not found in the active Insights tenant, or is not visible there. on a 404 — a group the directory can't resolve also 404s here, so a 404 alone isn't proof the stored group doesn't exist. If every Insights RBAC command 404s, the tenant likely doesn't have the Insights Portal service provisioned.

See also

• Insights overview
• users, roles — the other RBAC read surfaces; roles maps the role names shown here to their GUIDs and back.