Admin - Groups GetGroupsAsAdmin

Service:
Power BI REST APIs
API Version:
v1.0

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 or authenticate via service principal.
This API allows 200 requests per hour at maximum.

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}
With optional parameters: 
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
$top
 query True
  • integer
int32

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

Expands related entities inline, receives a comma-separated list of data types. Supported: users, reports, dashboards, datasets, dataflows, workbooks
$filter
 query
  • string

Filters the results based on a boolean condition
$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 dashboards expanded
Get workspaces with datasets expanded
Get workspaces with datasets expanded (only applicable for workspaces in the new workspace experience)
Get workspaces with reports expanded
Get workspaces with users expanded (only applicable for workspaces in the new workspace experience)
Get workspaces with workbooks expanded

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

Status code:
200 
{
  "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

Status code:
200 
{
  "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 dashboards expanded

Sample Request

GET https://api.powerbi.com/v1.0/myorg/admin/groups?$expand=dashboards&$top=100

Sample Response

Status code:
200 
{
  "value": [
    {
      "id": "94E57E92-CEE2-486D-8CC8-218C97200579",
      "isReadOnly": false,
      "isOnDedicatedCapacity": false,
      "capacityMigrationStatus": "Migrated",
      "description": "shorter description",
      "type": "Workspace",
      "state": "Removing",
      "name": "a",
      "dashboards": [
        {
          "id": "4668133c-ae3f-42fb-ad7c-214a8623280c",
          "displayName": "SQlAzure-Refresh.pbix",
          "isReadOnly": false
        },
        {
          "id": "a8f18ca7-63e8-4220-bc1c-f576ec180b98",
          "displayName": "cdvc",
          "isReadOnly": false
        }
      ]
    }
  ]
}

Get workspaces with datasets expanded

Sample Request

GET https://api.powerbi.com/v1.0/myorg/admin/groups?$expand=datasets&$top=100

Sample Response

Status code:
200 
{
  "value": [
    {
      "id": "94E57E92-CEE2-486D-8CC8-218C97200579",
      "isReadOnly": false,
      "isOnDedicatedCapacity": false,
      "capacityMigrationStatus": "Migrated",
      "description": "shorter description",
      "type": "Workspace",
      "state": "Removing",
      "name": "a",
      "datasets": [
        {
          "id": "8ce96c50-85a0-4db3-85c6-7ccc3ed46523",
          "name": "SQlAzure-Refresh",
          "addRowsAPIEnabled": false,
          "configuredBy": "admin@granularcontrols.ccsctp.net",
          "isRefreshable": true,
          "isEffectiveIdentityRequired": false,
          "isEffectiveIdentityRolesRequired": false,
          "isOnPremGatewayRequired": false,
          "targetStorageMode": "Abf",
          "createdDate": "2019-04-30T21:35:15.867-07:00",
          "ContentProviderType": "PbixInImportMode"
        },
        {
          "id": "7d6a4f72-1906-4e08-a469-bd6bc1ab7b69",
          "name": "NESGames",
          "addRowsAPIEnabled": false,
          "configuredBy": "admin@granularcontrols.ccsctp.net",
          "isRefreshable": true,
          "isEffectiveIdentityRequired": false,
          "isEffectiveIdentityRolesRequired": false,
          "isOnPremGatewayRequired": false,
          "targetStorageMode": "Abf",
          "createdDate": "2019-04-30T21:35:15.867-07:00",
          "ContentProviderType": "PbixInImportMode"
        }
      ]
    }
  ]
}

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

Sample Request

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

Sample Response

Status code:
200 
{
  "value": [
    {
      "id": "e380d1d0-1fa6-460b-9a90-1a5c6b02414c",
      "isReadOnly": false,
      "isOnDedicatedCapacity": false,
      "name": "Sample Group 1",
      "description": "Sample group",
      "type": "Workspace",
      "state": "Active",
      "datasets": [
        {
          "id": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
          "name": "SalesMarketing",
          "addRowsAPIEnabled": false,
          "configuredBy": "john@contoso.com",
          "isRefreshable": true,
          "isEffectiveIdentityRequired": false,
          "isEffectiveIdentityRolesRequired": false,
          "isOnPremGatewayRequired": false,
          "encryption": {
            "id": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
            "encryptionStatus": "InSyncWithWorkspace"
          }
        }
      ]
    },
    {
      "id": "183dcf10-47b8-48c4-84aa-f0bf9d5f8fcf",
      "isReadOnly": false,
      "isOnDedicatedCapacity": false,
      "name": "Sample Group 2",
      "description": "Deleted sample group",
      "type": "Workspace",
      "state": "Deleted",
      "datasets": []
    }
  ]
}

Get workspaces with reports expanded

Sample Request

GET https://api.powerbi.com/v1.0/myorg/admin/groups?$expand=reports&$top=100

Sample Response

Status code:
200 
{
  "value": [
    {
      "id": "EC1EE11F-845D-495E-82A3-9DAC2072305A",
      "isReadOnly": false,
      "isOnDedicatedCapacity": false,
      "capacityMigrationStatus": "Migrated",
      "description": "cvcv",
      "type": "Workspace",
      "state": "Active",
      "name": "WSv2Test12",
      "reports": []
    },
    {
      "id": "94E57E92-CEE2-486D-8CC8-218C97200579",
      "isReadOnly": false,
      "isOnDedicatedCapacity": false,
      "capacityMigrationStatus": "Migrated",
      "description": "shorter description",
      "type": "Workspace",
      "state": "Removing",
      "name": "a",
      "reports": [
        {
          "id": "5DBA60B0-D9A7-42AE-B12C-6D9D51E7739A",
          "reportType": "PowerBIReport",
          "name": "SQlAzure-Refresh",
          "datasetId": "8ce96c50-85a0-4db3-85c6-7ccc3ed46523"
        },
        {
          "id": "197E5C3C-D2F3-42D8-A536-875FB6D7D48C",
          "reportType": "PowerBIReport",
          "name": "NESGames",
          "datasetId": "7d6a4f72-1906-4e08-a469-bd6bc1ab7b69"
        }
      ]
    }
  ]
}

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

Status code:
200 
{
  "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": []
    }
  ]
}

Get workspaces with workbooks expanded

Sample Request

GET https://api.powerbi.com/v1.0/myorg/admin/groups?$expand=workbooks&$top=100

Sample Response

Status code:
200 
{
  "value": [
    {
      "id": "94E57E92-CEE2-486D-8CC8-218C97200579",
      "isReadOnly": false,
      "isOnDedicatedCapacity": false,
      "description": "shorter description",
      "type": "Workspace",
      "state": "Removing",
      "name": "a",
      "workbooks": [
        {
          "name": "My Excel sheet",
          "datasetId": "8ce96c50-85a0-4db3-85c6-7ccc3ed46523"
        }
      ]
    }
  ]
}

Definitions

Dashboard

A Power BI dashboard. Below is a list of properties that may be returned for a dashboard. Only a subset of the properties will be returned depending on the API called, the caller permissions and the availability of the data in the Power BI database.
Dataflow

The metadata of a dataflow. Below is a list of properties that may be returned for a dataflow. Only a subset of the properties will be returned depending on the API called, the caller permissions and the availability of the data in the Power BI database.
Dataset

A Power BI dataset. Below is a list of properties that may be returned for a dataset. Only a subset of the properties will be returned depending on the API called, the caller permissions and the availability of the data in the Power BI database.
DatasourceUsage

Datasource usage
DependentDataflow

A Power BI Dependent dataflow
Encryption

Encryption information for a dataset
EncryptionStatus

Dataset encryption status
EndorsementDetails

Power BI endorsement details
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
Report

A Power BI report. Below is a list of properties that may be returned for a report. Only a subset of the properties will be returned depending on the API called, the caller permissions and the availability of the data in the Power BI database.
SensitivityLabel

Artifact sensitivity label info
Tile

A Power BI tile
Workbook

A Power BI workbook

Dashboard

A Power BI dashboard. Below is a list of properties that may be returned for a dashboard. Only a subset of the properties will be returned depending on the API called, the caller permissions and the availability of the data in the Power BI database.

Name Type Description
dataClassification
  • string

The data classification tag of the dashboard
displayName
  • string

The dashboard display name
embedUrl
  • string

The dashboard embed url
id
  • string

The dashboard id
isReadOnly
  • boolean

Is ReadOnly dashboard
sensitivityLabel

The dashboard sensitivity label
tiles

The tiles that belong to the dashboard.

Dataflow

The metadata of a dataflow. Below is a list of properties that may be returned for a dataflow. Only a subset of the properties will be returned depending on the API called, the caller permissions and the availability of the data in the Power BI database.

Name Type Description
configuredBy
  • string

The dataflow owner
datasourceUsages

Datasource usages
description
  • string

The dataflow description
endorsementDetails

The dataflow endorsement details
modelUrl
  • string

A URL to the dataflow definition file (model.json)
modifiedBy
  • string

The user that modified this dataflow
modifiedDateTime
  • string

modification date time
name
  • string

The dataflow name
objectId
  • string

The dataflow id
sensitivityLabel

The dataflow sensitivity label
upstreamDataflows

Upstream Dataflows

Dataset

A Power BI dataset. Below is a list of properties that may be returned for a dataset. Only a subset of the properties will be returned depending on the API called, the caller permissions and the availability of the data in the Power BI database.

Name Type Description
ContentProviderType
  • string

The content provider type for the dataset
CreateReportEmbedURL
  • string

The dataset create report embed url
CreatedDate
  • string

DateTime of creation of this dataset
Encryption

The dataset encryption information (Only applicable when $expand is specified)
IsEffectiveIdentityRequired
  • boolean

Whether the dataset requires an effective identity. This indicates that you must send an effective identity using the GenerateToken API.
IsEffectiveIdentityRolesRequired
  • boolean

Whether RLS is defined inside the PBIX file. This indicates that you must specify a role.
IsOnPremGatewayRequired
  • boolean

Dataset requires an On-premises Data Gateway
IsRefreshable
  • boolean

Can this dataset be refreshed
QnaEmbedURL
  • string

The dataset qna embed url
addRowsAPIEnabled
  • boolean

Whether the dataset allows adding new rows
configuredBy
  • string

The dataset owner
datasourceUsages

Datasource usages
description
  • string

The dataset description
endorsementDetails

The dataset endorsement details
id
  • string

The dataset id
name
  • string

The dataset name
sensitivityLabel

The dataset sensitivity label
upstreamDataflows

Upstream Dataflows
webUrl
  • string

The dataset web url

DatasourceUsage

Datasource usage

Name Type Description
datasourceInstanceId
  • string

The datasource instance ID

DependentDataflow

A Power BI Dependent dataflow

Name Type Description
groupId
  • string

The target group id
targetDataflowId
  • string

The target dataflow id

Encryption

Encryption information for a dataset

Name Type Description
EncryptionStatus

Dataset encryption status

EncryptionStatus

Dataset encryption status

Name Type Description
InSyncWithWorkspace
  • string

Encryption is supported and is in sync with the encryption settings
NotInSyncWithWorkspace
  • string

Encryption is supported and not in sync with the encryption settings
NotSupported
  • string

Encryption is not supported for this dataset
Unknown
  • string

Unable to determine state due to dataset corruption

EndorsementDetails

Power BI endorsement details

Name Type Description
certifiedBy
  • string

The user that certified the artifact
endorsement
  • string

The endorsement status

Group

A Power BI group

Name Type Description
capacityId
  • string

The capacity id
dashboards

The dashboards that belong to the group. Available only for admin API calls.
dataflowStorageId
  • string

The Power BI dataflow storage account id
dataflows

The dataflows that belong to the group. Available only for admin API calls.
datasets

The datasets that belong to the group. Available only for admin API calls.
description
  • string

The group description. Available only for admin API calls.
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
reports

The reports that belong to the group. Available only for admin API calls.
state
  • string

The group state. Available only for admin API calls.
type
  • string

The type of group. Available only for admin API calls.
users

The users that belong to the group, and their access rights. Available only for admin API calls.
workbooks

The workbooks that belong to the group. Available only for admin API calls.

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 Explore access to content in group
Member
  • string

Grants Read, Reshare and Explore access to content in workspace
None
  • string

Removes permission to content in workspace
Viewer
  • string

Grants Read only access to content in group

PrincipalType

The principal type

Name Type Description
App
  • string

Service principal type
Group
  • string

Group principal type
User
  • string

User principal type

Report

A Power BI report. Below is a list of properties that may be returned for a report. Only a subset of the properties will be returned depending on the API called, the caller permissions and the availability of the data in the Power BI database.

Name Type Description
createdBy
  • string

The report owner
createdDateTime
  • string

The report created date time.
datasetId
  • string

The dataset id
description
  • string

The report description
embedUrl
  • string

The report embed url
endorsementDetails

The report endorsement details
id
  • string

The report id
modifiedBy
  • string

The user that modified this report
modifiedDateTime
  • string

The report modified date time.
name
  • string

The report name
reportType enum:
  • PaginatedReport

The report type
sensitivityLabel

The report sensitivity label
webUrl
  • string

The report web url

SensitivityLabel

Artifact sensitivity label info

Name Type Description
labelId
  • string

The sensitivity label ID

Tile

A Power BI tile

Name Type Description
colSpan
  • integer

number of columns a tile should span
datasetId
  • string

The dataset id. Available only for tiles created from a report or using a dataset; for example, Q&A tiles.
embedData
  • string

The tile embed data
embedUrl
  • string

The tile embed url
id
  • string

The tile id
reportId
  • string

The report id. Available only for tiles created from a report.
rowSpan
  • integer

number of rows a tile should span
title
  • string

The dashboard display name

Workbook

A Power BI workbook

Name Type Description
datasetId
  • string

DatasetId for workbooks. Only applies for workbooks that has an associated dataset.
name
  • string

The workbook name