Admin - Groups GetGroupsAsAdmin

Returns a list of workspaces for the organization.
Note: The user must have administrator rights (such as Office 365 Global Administrator or Power BI Service Administrator) to call this API.

Required scope: Tenant.Read.All or Tenant.ReadWrite.All
To set the permissions scope, see Register an app.

GET https://api.powerbi.com/v1.0/myorg/admin/groups
GET https://api.powerbi.com/v1.0/myorg/admin/groups?$expand={$expand}&$filter={$filter}&$top={$top}&$skip={$skip}

URI Parameters

Name In Required Type Description
$expand
query
  • string

Expands related entities inline

$filter
query
  • string

Filters the results based on a boolean condition

$top
query
  • integer
int32

Returns only the first n results

$skip
query
  • integer
int32

Skips the first n results

Responses

Name Type Description
200 OK

OK

Examples

Get deleted workspaces (only applicable for workspaces in the new workspace experience)
Get orphaned workspaces (only applicable for workspaces in the new workspace experience)
Get workspaces with users expanded (only applicable for workspaces in the new workspace experience)

Get deleted workspaces (only applicable for workspaces in the new workspace experience)

Sample Request

GET https://api.powerbi.com/v1.0/myorg/admin/groups?$filter=state eq 'Deleted'

Sample Response

{
  "value": [
    {
      "id": "183dcf10-47b8-48c4-84aa-f0bf9d5f8fcf",
      "isReadOnly": false,
      "isOnDedicatedCapacity": false,
      "name": "Sample Group 2",
      "description": "Deleted sample group",
      "type": "Workspace",
      "state": "Deleted"
    }
  ]
}

Get orphaned workspaces (only applicable for workspaces in the new workspace experience)

Sample Request

GET https://api.powerbi.com/v1.0/myorg/admin/groups?$expand=users&$filter=(not users/any()) or (not users/any(u: u/groupUserAccessRight eq Microsoft.PowerBI.ServiceContracts.Api.GroupUserAccessRight'Admin'))

Sample Response

{
  "value": [
    {
      "id": "d5caa808-8c91-400a-911d-06af08dbcc31",
      "isReadOnly": false,
      "isOnDedicatedCapacity": false,
      "name": "Orphaned Group",
      "description": "Sample orphan group",
      "type": "Workspace",
      "state": "Active",
      "users": []
    }
  ]
}

Get workspaces with users expanded (only applicable for workspaces in the new workspace experience)

Sample Request

GET https://api.powerbi.com/v1.0/myorg/admin/groups?$expand=users

Sample Response

{
  "value": [
    {
      "id": "e380d1d0-1fa6-460b-9a90-1a5c6b02414c",
      "isReadOnly": false,
      "isOnDedicatedCapacity": false,
      "name": "Sample Group 1",
      "description": "Sample group",
      "type": "Workspace",
      "state": "Active",
      "users": [
        {
          "emailAddress": "john@contoso.com",
          "groupUserAccessRight": "Admin"
        }
      ]
    },
    {
      "id": "183dcf10-47b8-48c4-84aa-f0bf9d5f8fcf",
      "isReadOnly": false,
      "isOnDedicatedCapacity": false,
      "name": "Sample Group 2",
      "description": "Deleted sample group",
      "type": "Workspace",
      "state": "Deleted",
      "users": []
    }
  ]
}

Definitions

Group

A Power BI group

GroupUserAccessRight

A Power BI user access right entry for workspace

GroupUserAccessRightEnum

Access rights user has for the workspace

ODataResponse[List[Group]]

Odata response wrapper for a Power BI group list

PrincipalType

The principal type

Group

A Power BI group

Name Type Description
capacityId
  • string

The capacity id

description
  • string

The group description

id
  • string

The workspace id

isOnDedicatedCapacity
  • boolean

Is the group on dedicated capacity

isReadOnly
  • boolean

Is the group read only

name
  • string

The group name

state
  • string

The group state

type
  • string

The type of group

users

The users that belong to the group, and their access rights.

GroupUserAccessRight

A Power BI user access right entry for workspace

Name Type Description
displayName
  • string

Display name of the principal

emailAddress
  • string

Email address of the user

groupUserAccessRight

Access rights user has for the workspace

identifier
  • string

Identifier of the principal

principalType

The principal type

GroupUserAccessRightEnum

Access rights user has for the workspace

Name Type Description
Admin
  • string

Grants administrator rights to workspace

Contributor
  • string

Grants read and write access to content in group

Member
  • string

Grants read access to content in workspace

None
  • string

Removes permission to content in workspace

ODataResponse[List[Group]]

Odata response wrapper for a Power BI group list

Name Type Description
odata.context
  • string

OData context

value

The groups

PrincipalType

The principal type

Name Type Description
Group
  • string

Group principal type

User
  • string

User principal type