Groups - Get Groups

Returns a list of workspaces the user has access to.

Note: Users that have been recently added to a group may not have their new group immediately available, see Refresh user permissions.

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

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

URI Parameters

Name In Required Type Description
$filter
query
  • string

Filters the results, based on a boolean condition

$skip
query
  • integer
int32

Skips the first n results

$top
query
  • integer
int32

Returns only the first n results

Responses

Name Type Description
200 OK

OK

Examples

example
example with filter

example

Sample Request

GET https://api.powerbi.com/v1.0/myorg/groups

Sample Response

{
  "value": [
    {
      "id": "f089354e-8366-4e18-aea3-4cb4a3a50b48",
      "isReadOnly": false,
      "isOnDedicatedCapacity": false,
      "name": "sample group"
    },
    {
      "id": "3d9b93c6-7b6d-4801-a491-1738910904fd",
      "isReadOnly": false,
      "isOnDedicatedCapacity": false,
      "name": "marketing group"
    },
    {
      "id": "a2f89923-421a-464e-bf4c-25eab39bb09f",
      "isReadOnly": false,
      "isOnDedicatedCapacity": false,
      "name": "contoso",
      "dataflowStorageId": "d692ae06-708c-485e-9987-06ff0fbdbb1f"
    }
  ]
}

example with filter

Sample Request

GET https://api.powerbi.com/v1.0/myorg/groups?$filter=$filter=contains(name,'marketing')%20or%20name%20eq%20'contoso'

Sample Response

{
  "value": [
    {
      "id": "3d9b93c6-7b6d-4801-a491-1738910904fd",
      "isReadOnly": false,
      "isOnDedicatedCapacity": false,
      "name": "marketing group"
    },
    {
      "id": "a2f89923-421a-464e-bf4c-25eab39bb09f",
      "isReadOnly": false,
      "isOnDedicatedCapacity": false,
      "name": "contoso",
      "dataflowStorageId": "d692ae06-708c-485e-9987-06ff0fbdbb1f"
    }
  ]
}

Definitions

ASMashupExpression

A dataset table source

Column

A dataset column

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.

DashboardUser

A Power BI user access right entry for dashboard

DashboardUserAccessRight

Access rights user has for the dashboard (Permission level)

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.

DataflowUser

A Power BI user access right entry for dataflow

DataflowUserAccessRight

Access rights user has for the dataflow (Permission level)

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.

DatasetUser

A Power BI user access right entry for dataset

DatasetUserAccessRight

Access rights user has for the dataset (Permission level)

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 (Permission level)

Measure

A Power BI measure

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.

ReportUser

A Power BI user access right entry for report

ReportUserAccessRight

Access rights user has for the report (Permission level)

Row

A data row in a dataset

SensitivityLabel

Artifact sensitivity label info

Table

A dataset table

Tile

A Power BI tile

Workbook

A Power BI workbook

ASMashupExpression

A dataset table source

Name Type Description
expression
  • string

The source expression

Column

A dataset column

Name Type Description
dataCategory
  • string

(Optional) String value to be used for the data category which describes the data within this column

dataType
  • string

The column data type

formatString
  • string

(Optional) The format of the column as specified in FORMAT_STRING

isHidden
  • boolean

(Optional) Property indicating if the column is hidden from view. Default is false.

name
  • string

The column name

sortByColumn
  • string

(Optional) String name of a column in the same table to be used to order the current column

summarizeBy
  • string

(Optional) Aggregate Function to use for summarizing this column

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.

users

The Dashboard User Access Details. This value will be empty. It will be removed from the payload response in an upcoming release. To retrieve user information on an artifact, please consider using the Get Dashboard User as Admin APIs, or the PostWorkspaceInfo API with the getArtifactUser parameter.

DashboardUser

A Power BI user access right entry for dashboard

Name Type Description
dashboardUserAccessRight

Access rights user has for the dashboard (Permission level)

displayName
  • string

Display name of the principal

emailAddress
  • string

Email address of the user

graphId
  • string

Identifier of the principal in Microsoft Graph. Only available for admin APIs.

identifier
  • string

Identifier of the principal

principalType

The principal type

DashboardUserAccessRight

Access rights user has for the dashboard (Permission level)

Name Type Description
None
  • string

No permission to content in dashboard

Owner
  • string

Grants Read, Write and Reshare access to content in report

Read
  • string

Grants Read access to content in dashboard

ReadCopy
  • string

Grants Read and Copy access to content in dashboard

ReadReshare
  • string

Grants Read and Reshare access to content in dashboard

ReadWrite
  • string

Grants Read and Write access to content in 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

users

The Dataflow User Access Details. This value will be empty. It will be removed from the payload response in an upcoming release. To retrieve user information on an artifact, please consider using the Get Dataflow User as Admin APIs, or the PostWorkspaceInfo API with the getArtifactUser parameter.

DataflowUser

A Power BI user access right entry for dataflow

Name Type Description
DataflowUserAccessRight

Access rights user has for the dataflow (Permission level)

displayName
  • string

Display name of the principal

emailAddress
  • string

Email address of the user

graphId
  • string

Identifier of the principal in Microsoft Graph. Only available for admin APIs.

identifier
  • string

Identifier of the principal

principalType

The principal type

DataflowUserAccessRight

Access rights user has for the dataflow (Permission level)

Name Type Description
None
  • string

Removes permission to content in dataflow

Owner
  • string

Grants Read, Write and Reshare access to content in dataflow

Read
  • string

Grants Read access to content in dataflow

ReadReshare
  • string

Grants Read and Reshare access to content in dataflow

ReadWrite
  • string

Grants Read and Write access to content in dataflow

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

schemaMayNotBeUpToDate
  • boolean

Whether dataset schema may not be up to date

schemaRetrievalError
  • string

The dataset schema retrieval error

sensitivityLabel

The dataset sensitivity label. Only available for admin APIs.

tables

The dataset tables

upstreamDataflows

Upstream Dataflows

users

The Dataset User Access Details. This value will be empty. It will be removed from the payload response in an upcoming release. To retrieve user information on an artifact, please consider using the Get Dataset User as Admin APIs, or the PostWorkspaceInfo API with the getArtifactUser parameter.

webUrl
  • string

The dataset web url

DatasetUser

A Power BI user access right entry for dataset

Name Type Description
datasetUserAccessRight

Access rights user has for the dataset (Permission level)

displayName
  • string

Display name of the principal

emailAddress
  • string

Email address of the user

graphId
  • string

Identifier of the principal in Microsoft Graph. Only available for admin APIs.

identifier
  • string

Identifier of the principal

principalType

The principal type

DatasetUserAccessRight

Access rights user has for the dataset (Permission level)

Name Type Description
None
  • string

Removes permission to content in dataset

Read
  • string

Grants Read access to content in dataset

ReadExplore
  • string

Grants Read and Explore access to content in dataset

ReadReshare
  • string

Grants Read and Reshare access to content in dataset

ReadReshareExplore
  • string

Grants Read, Reshare and Explore access to content in dataset

ReadWrite
  • string

Grants Read and Write access to content in dataset

ReadWriteExplore
  • string

Grants Read, Write and Explore access to content in dataset

ReadWriteReshare
  • string

Grants Read, Write and Reshare access to content in dataset

ReadWriteReshareExplore
  • string

Grants Read, Write, Reshare and Explore access to content in dataset

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

pipelineId
  • string

The deployment pipeline ID that the workspace is assigned to. Available only for workspaces in the new workspace experience and only for admin API calls.

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. This value will be empty. It will be removed from the payload response in an upcoming release. To retrieve user information on an artifact, please consider using the Get Group User APIs, or the PostWorkspaceInfo API with the getArtifactUser parameter.

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

graphId
  • string

Identifier of the principal in Microsoft Graph. Only available for admin APIs.

groupUserAccessRight

Access rights user has for the workspace (Permission level)

identifier
  • string

Object ID of the principal

principalType

The principal type

GroupUserAccessRight

Access rights user has for the workspace (Permission level)

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

Measure

A Power BI measure

Name Type Description
description
  • string

(Optional) Measure description

expression
  • string

A valid DAX expression

formatString
  • string

(Optional) A string describing how the value should be formatted when it is displayed as specified in FORMAT_STRING

isHidden
  • boolean

(Optional) Is measure hidden

name
  • string

The measure name

PrincipalType

The principal type

Name Type Description
App
  • string

Service principal type

Group
  • string

Group principal type

None
  • string

None principal type, used for whole organization level access.

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. Available only for reports created after June 2019.

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

users

The Report User Access Details. This value will be empty. It will be removed from the payload response in an upcoming release. To retrieve user information on an artifact, please consider using the Get Report User as Admin APIs, or the PostWorkspaceInfo API with the getArtifactUser parameter.

webUrl
  • string

The report web url

ReportUser

A Power BI user access right entry for report

Name Type Description
displayName
  • string

Display name of the principal

emailAddress
  • string

Email address of the user

graphId
  • string

Identifier of the principal in Microsoft Graph. Only available for admin APIs.

identifier
  • string

Identifier of the principal

principalType

The principal type

reportUserAccessRight

Access rights user has for the report (Permission level)

ReportUserAccessRight

Access rights user has for the report (Permission level)

Name Type Description
None
  • string

No permission to content in report

Owner
  • string

Grants Read, Write and Reshare access to content in report

Read
  • string

Grants Read access to content in report

ReadCopy
  • string

Grants Read and Copy access to content in report

ReadReshare
  • string

Grants Read and Reshare access to content in report

ReadWrite
  • string

Grants Read and Write access to content in report

Row

A data row in a dataset

Name Type Description
id
  • string

The unique row ID

SensitivityLabel

Artifact sensitivity label info

Name Type Description
labelId
  • string

The sensitivity label ID

Table

A dataset table

Name Type Description
columns

The column schema for this table

description
  • string

The table description

isHidden
  • boolean

(Optional) Whether dataset table is hidden

measures

The measures within this table

name
  • string

The table name

rows

The data rows within this table

source

The table source

Tile

A Power BI tile

Name Type Description
colSpan
  • integer

number of columns a tile should span

datasetId
  • string

The dataset ID, which is available only for tiles created from a report or using a dataset, such as 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, which is 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