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?$top={$top}
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 True
  • integer
int32

Returns only the first n results. This parameter is mandatory and must be in the range of 1-5000.

$skip
query
  • integer
int32

Skips the first n results. Use with top to fetch results beyond the first 5000.

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'&$top=100

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'))&$top=100

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&$top=100

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

Groups

Odata response wrapper for a Power BI group list

GroupUser

A Power BI user access right entry for workspace

GroupUserAccessRight

Access rights user has for the workspace

PrincipalType

The principal type

Group

A Power BI group

Name Type Description
capacityId
  • string

The capacity id

dataflowStorageId
  • string

The Power BI dataflow storage account 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.

Groups

Odata response wrapper for a Power BI group list

Name Type Description
odata.context
  • string

OData context

value

The groups

GroupUser

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

GroupUserAccessRight

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

PrincipalType

The principal type

Name Type Description
App
  • string

Service principal type

Group
  • string

Group principal type

User
  • string

User principal type