UiPath Documentation
uipath-cli
latest
false
UiPath CLI user guide

uip insights roles

Syntax and options for `uip insights roles`, which reads the Insights roles of the active tenant.

uip insights roles reads the Insights roles defined in the active tenant. This is a read-only surface — there is no create, update, or delete verb.

Important:

Reading Insights roles 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 roles list [--include-resource] [-l <n>] [-o <n>]
uip insights roles get <role-id> [--include-resource]
uip insights roles list [--include-resource] [-l <n>] [-o <n>]
uip insights roles get <role-id> [--include-resource]

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 roles list​

List Insights roles visible to the current caller. The list can be entitlement-filtered — a tenant without the full-mode entitlement only sees the readonly role set — and listing can trigger a cached call to Licensing to check that entitlement.

Options​

FlagDescription
--include-resourceInclude the role resource string, which can carry the organization and tenant GUIDs, in the output. Off by default.
-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 roles list

uip insights roles list --include-resource --limit 100
uip insights roles list

uip insights roles list --include-resource --limit 100

Data shape — default view​

{
  "Code": "InsightsRolesList",
  "Data": [
    { "id": "c1d2e3f4-0000-0000-0000-000000000001", "name": "Viewer", "actions": ["Read"] }
  ],
  "Pagination": { "Returned": 1, "Limit": 50, "Offset": 0, "Total": 1, "HasMore": false },
  "Instructions": "Role names can be entitlement-filtered: a role missing from this list can still exist and 'roles get' can still resolve it. Listing roles can trigger a cached entitlement call to Licensing. 'uip insights users list' and 'uip insights groups list' show these roles by name on each principal's row. This view omits the role resource string, which can carry the organization and tenant GUIDs. Pass --include-resource to include it."
}
{
  "Code": "InsightsRolesList",
  "Data": [
    { "id": "c1d2e3f4-0000-0000-0000-000000000001", "name": "Viewer", "actions": ["Read"] }
  ],
  "Pagination": { "Returned": 1, "Limit": 50, "Offset": 0, "Total": 1, "HasMore": false },
  "Instructions": "Role names can be entitlement-filtered: a role missing from this list can still exist and 'roles get' can still resolve it. Listing roles can trigger a cached entitlement call to Licensing. 'uip insights users list' and 'uip insights groups list' show these roles by name on each principal's row. This view omits the role resource string, which can carry the organization and tenant GUIDs. Pass --include-resource to include it."
}

Data shape — with --include-resource​

{
  "Code": "InsightsRolesList",
  "Data": [
    {
      "id": "c1d2e3f4-0000-0000-0000-000000000001",
      "name": "Viewer",
      "actions": ["Read"],
      "resource": "orn:orch:tenant:t1:role:Viewer"
    }
  ],
  "Pagination": { "Returned": 1, "Limit": 50, "Offset": 0, "Total": 1, "HasMore": false }
}
{
  "Code": "InsightsRolesList",
  "Data": [
    {
      "id": "c1d2e3f4-0000-0000-0000-000000000001",
      "name": "Viewer",
      "actions": ["Read"],
      "resource": "orn:orch:tenant:t1:role:Viewer"
    }
  ],
  "Pagination": { "Returned": 1, "Limit": 50, "Offset": 0, "Total": 1, "HasMore": false }
}

With --include-resource, Instructions carries the same note without its last two sentences. An empty list is a successful result, not an error: Instructions keeps the role-filtering note and drops the sentences about the omitted resource string.

uip insights roles get​

Get one Insights role by its GUID. The list's entitlement filter does not apply here — get can resolve a role that list filtered out.

Arguments​

NameRequiredPurpose
<role-id>yesRole GUID. Must be a real GUID — a malformed value fails client-side with Run 'uip insights roles list' to find a role ID. before any network call.

Options​

FlagDescription
--include-resourceInclude the role resource string in the output. Off by default.

Example​

uip insights roles get c1d2e3f4-0000-0000-0000-000000000001
uip insights roles get c1d2e3f4-0000-0000-0000-000000000001

Data shape (--output json)​

{
  "Code": "InsightsRoleGet",
  "Data": { "id": "c1d2e3f4-0000-0000-0000-000000000001", "name": "Viewer", "actions": ["Read"] }
}
{
  "Code": "InsightsRoleGet",
  "Data": { "id": "c1d2e3f4-0000-0000-0000-000000000001", "name": "Viewer", "actions": ["Read"] }
}

With --include-resource, the same shape gains a resource field, same as the list view.

Role <id> was not found in the active Insights tenant, or is not visible there. on a 404 — if every Insights RBAC command 404s, the tenant likely doesn't have the Insights Portal service provisioned.

See also​

Was this page helpful?

Connect

Need help? Support(opens in new window)

Want to learn? UiPath Academy(opens in new window)

Have questions? UiPath Forum(opens in new window)

Stay updated