Admin - Groups UpdateGroupAsAdmin

Service:

Power BI REST APIs

API Version:

v1.0

Updates the properties of the specified workspace.

To unassign a Log Analytics workspace, explicitly set the value to null.

Permissions

The user must be a Fabric administrator.

Required Scope

Tenant.ReadWrite.All

Limitations

• Maximum 200 requests per hour.
• For Shared capacities, only the name and description can be updated.
• For Premium capacities, only the name, description, defaultDatasetStorageFormat and Log Analytics workspace can be updated.
• The name must be unique inside an organization.
  
  

PATCH https://api.powerbi.com/v1.0/myorg/admin/groups/{groupId}

URI Parameters

Name	In	Required	Type	Description
groupId	path	True	string uuid	The workspace ID

Request Body

Name	Required	Type	Description
id	True	string	The workspace ID
capacityId		string	The capacity ID
dashboards		AdminDashboard[]	The dashboards that belong to the group
dataflowStorageId		string	The Power BI dataflow storage account ID
dataflows		AdminDataflow[]	The dataflows that belong to the group
datasets		AdminDataset[]	The datasets that belong to the group
defaultDatasetStorageFormat		DefaultDatasetStorageFormat	The default dataset storage format in the workspace. Returned only when isOnDedicatedCapacity is true
description		string	The group description
hasWorkspaceLevelSettings		boolean	Whether the workspace has custom settings
isOnDedicatedCapacity		boolean	Whether the group is assigned to a dedicated capacity
isReadOnly		boolean	Whether the group is read-only
logAnalyticsWorkspace		AzureResource	The Log Analytics workspace assigned to the group. This is returned only when retrieving a single group.
name		string	The group name
pipelineId		string	The deployment pipeline ID that the workspace is assigned to.
reports		AdminReport[]	The reports that belong to the group
state		string	The group state
type		GroupType	The type of group being returned.
users		GroupUser[]	(Empty value) The users that belong to the group and their access rights. This property will be removed from the payload response in an upcoming release. You can retrieve user information on a Power BI item (such as a report or a dashboard) by using the Get Group Users As Admin API call, or the PostWorkspaceInfo API call with the getArtifactUsers parameter.
workbooks		Workbook[]	The workbooks that belong to the group

Responses

Name	Type	Description
200 OK		OK

Examples

Example of assigning Log Analytics workspace

Example of unassigning Log Analytics workspace

Example of updating group description and defaultDatasetStorageFormat

Example of assigning Log Analytics workspace

Sample request

PATCH https://api.powerbi.com/v1.0/myorg/admin/groups/e2284830-c8dc-416b-b19a-8cdcd2729332

Request Body

{
  "logAnalyticsWorkspace": {
    "subscriptionId": "d778934f-bda2-41d9-b5c7-6cf41372c1a0",
    "resourceGroup": "myResourceGroup",
    "resourceName": "myLogAnalyticsWorkspace"
  }
}

Sample response

Status code:

200

Example of unassigning Log Analytics workspace

Sample request

PATCH https://api.powerbi.com/v1.0/myorg/admin/groups/e2284830-c8dc-416b-b19a-8cdcd2729332

Request Body

{
  "logAnalyticsWorkspace": null
}

Sample response

Status code:

200

Example of updating group description and defaultDatasetStorageFormat

Sample request

PATCH https://api.powerbi.com/v1.0/myorg/admin/groups/e2284830-c8dc-416b-b19a-8cdcd2729332

Request Body

{
  "name": "Updated Sales Results",
  "description": "Refreshed sales numbers",
  "defaultDatasetStorageFormat": "Large"
}

Sample response

Status code:

200

Definitions

Name	Description
AdminDashboard	A Power BI dashboard returned by Admin APIs. The API returns a subset of the following list of dashboard properties. The subset depends on the API called, caller permissions, and the availability of data in the Power BI database.
AdminDataflow	The metadata of a dataflow returned by Admin APIs. 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.
AdminDataset	A Power BI dataset returned by Admin APIs. The API returns a subset of the following list of dataset properties. The subset depends on the API called, caller permissions, and the availability of the data in the Power BI database.
AdminGroup	A Power BI group returned by admin APIs
AdminReport	A Power BI report returned by Admin APIs. The API returns a subset of the following list of report properties. The subset depends on the API called, caller permissions, and the availability of data in the Power BI database.
AdminTile	A Power BI tile returned by Admin APIs.
AzureResource	A response detailing a user-owned Azure resource such as a Log Analytics workspace.
DashboardUser	A Power BI user access right entry for a dashboard
DashboardUserAccessRight	The access right that the user has for the dashboard (permission level)
DataflowUser	A Power BI user access right entry for a dataflow
DataflowUserAccessRight	The access right that a user has for the dataflow (permission level)
DatasetQueryScaleOutSettings	Query scale-out settings of a dataset
DatasetUser	A Power BI user access right entry for a dataset
DatasetUserAccessRight	The access right that the user has for the dataset (permission level)
DefaultDatasetStorageFormat	The default dataset storage format in the group
DependentDataflow	A Power BI dependent dataflow
Encryption	Encryption information for a dataset
EncryptionStatus	Dataset encryption status
GroupType	The group type
GroupUser	A Power BI user with access to the workspace
GroupUserAccessRight	The access right (permission level) that a user has on the workspace
PrincipalType	The principal type
ReportUser	A Power BI user access right entry for a report
ReportUserAccessRight	The access right that the user has for the report (permission level)
ServicePrincipalProfile	A Power BI service principal profile. Only relevant for Power BI Embedded multi-tenancy solution.
Subscription	An email subscription for a Power BI item (such as a report or a dashboard)
SubscriptionUser	A Power BI email subscription user
Workbook	A Power BI workbook

AdminDashboard

A Power BI dashboard returned by Admin APIs. The API returns a subset of the following list of dashboard properties. The subset depends on the API called, caller permissions, and the availability of data in the Power BI database.

Name	Type	Description
appId	string	The app ID, returned only if the dashboard belongs to an app
displayName	string	The display name of the dashboard
embedUrl	string	The embed URL of the dashboard
id	string	The dashboard ID
isReadOnly	boolean	Whether the dashboard is read-only
subscriptions	Subscription[]	(Empty Value) The subscription details for a Power BI item (such as a report or a dashboard). This property will be removed from the payload response in an upcoming release. You can retrieve subscription information for a Power BI report by using the Get Report Subscriptions as Admin API call.
tiles	AdminTile[]	The tiles that belong to the dashboard
users	DashboardUser[]	(Empty value) The dashboard user access details. This property will be removed from the payload response in an upcoming release. You can retrieve user information on a Power BI dashboard by using the Get Dashboard Users as Admin API call, or the PostWorkspaceInfo API call with the getArtifactUsers parameter.
webUrl	string	The web URL of the dashboard
workspaceId	string	The workspace ID (GUID) of the dashboard. This property will be returned only in GetDashboardsAsAdmin.

AdminDataflow

The metadata of a dataflow returned by Admin APIs. 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
description	string	The dataflow description
modelUrl	string	A URL to the dataflow definition file (model.json)
modifiedBy	string	The user that modified the dataflow
modifiedDateTime	string	The date and time that the dataflow was last modified
name	string	The dataflow name
objectId	string	The dataflow ID
users	DataflowUser[]	(Empty value) The dataflow user access details. This property will be removed from the payload response in an upcoming release. You can retrieve user information on a Power BI dataflow by using the Get Dataflow Users as Admin API call, or the PostWorkspaceInfo API call with the getArtifactUser parameter.
workspaceId	string	The dataflow workspace ID.

AdminDataset

A Power BI dataset returned by Admin APIs. The API returns a subset of the following list of dataset properties. The subset depends on the API called, 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	The dataset creation date and time
Encryption	Encryption	Dataset encryption information. Only applicable when $expand is specified.
IsEffectiveIdentityRequired	boolean	Whether the dataset requires an effective identity, which you must send in a GenerateToken API call.
IsEffectiveIdentityRolesRequired	boolean	Whether row-level security is defined inside the Power BI .pbix file. If so, you must specify a role.
IsInPlaceSharingEnabled	boolean	Whether the dataset can be shared with external users to be consumed in their own tenant
IsOnPremGatewayRequired	boolean	Whether the dataset requires an on-premises data gateway
IsRefreshable	boolean	This field returns true when the dataset is either recently refreshed or is configured for automatic refresh, with the connection mode specifically set to 'Import'. The value will return false for other connection modes, such as 'DirectQuery' and 'LiveConnection', regardless of whether the dataset is manually refreshed or is set up for automatic refresh.
QnaEmbedURL	string	The dataset Q&A embed URL
addRowsAPIEnabled	boolean	Whether the dataset allows adding new rows
configuredBy	string	The dataset owner
description	string	The dataset description
id	string	The dataset ID
name	string	The dataset name
queryScaleOutSettings	DatasetQueryScaleOutSettings	Query scale-out settings of a dataset
targetStorageMode	string	The dataset storage mode
upstreamDataflows	DependentDataflow[]	The list of all the dataflows this item depends on
users	DatasetUser[]	(Empty value) The dataset user access details. This property will be removed from the payload response in an upcoming release. You can retrieve user information on a Power BI item (such as a report or a dashboard) by using the Get Dataset Users as Admin API, or the PostWorkspaceInfo API with the getArtifactUsers parameter.
webUrl	string	The web URL of the dataset
workspaceId	string	The dataset workspace ID. This property will be returned only in GetDatasetsAsAdmin.

AdminGroup

A Power BI group returned by admin APIs

Name	Type	Description
capacityId	string	The capacity ID
dashboards	AdminDashboard[]	The dashboards that belong to the group
dataflowStorageId	string	The Power BI dataflow storage account ID
dataflows	AdminDataflow[]	The dataflows that belong to the group
datasets	AdminDataset[]	The datasets that belong to the group
defaultDatasetStorageFormat	DefaultDatasetStorageFormat	The default dataset storage format in the workspace. Returned only when isOnDedicatedCapacity is true
description	string	The group description
hasWorkspaceLevelSettings	boolean	Whether the workspace has custom settings
id	string	The workspace ID
isOnDedicatedCapacity	boolean	Whether the group is assigned to a dedicated capacity
isReadOnly	boolean	Whether the group is read-only
logAnalyticsWorkspace	AzureResource	The Log Analytics workspace assigned to the group. This is returned only when retrieving a single group.
name	string	The group name
pipelineId	string	The deployment pipeline ID that the workspace is assigned to.
reports	AdminReport[]	The reports that belong to the group
state	string	The group state
type	GroupType	The type of group being returned.
users	GroupUser[]	(Empty value) The users that belong to the group and their access rights. This property will be removed from the payload response in an upcoming release. You can retrieve user information on a Power BI item (such as a report or a dashboard) by using the Get Group Users As Admin API call, or the PostWorkspaceInfo API call with the getArtifactUsers parameter.
workbooks	Workbook[]	The workbooks that belong to the group

AdminReport

A Power BI report returned by Admin APIs. The API returns a subset of the following list of report properties. The subset depends on the API called, caller permissions, and the availability of data in the Power BI database.

Name	Type	Description
appId	string	The app ID, returned only if the report belongs to an app
createdBy	string	The report owner. Available only for reports created after June 2019.
createdDateTime	string	The report creation date and time
datasetId	string	The dataset ID of the report
description	string	The report description
embedUrl	string	The embed URL of the report
id	string	The report ID
isOwnedByMe	boolean	Determine if the report is created by the current user.
modifiedBy	string	The last user that modified the report
modifiedDateTime	string	The date and time that the report was last modified
name	string	The name of the report
originalReportId	string	The actual report ID when the workspace is published as an app.
reportType	enum: PaginatedReport PowerBIReport	The report type
subscriptions	Subscription[]	(Empty Value) The subscription details for a Power BI item (such as a report or a dashboard). This property will be removed from the payload response in an upcoming release. You can retrieve subscription information for a Power BI report by using the Get Report Subscriptions as Admin API call.
users	ReportUser[]	(Empty value) The user access details for a Power BI report. This property will be removed from the payload response in an upcoming release. You can retrieve user information on a Power BI report by using the Get Report Users as Admin API call, or the PostWorkspaceInfo API call with the getArtifactUsers parameter.
webUrl	string	The web URL of the report
workspaceId	string	The workspace ID (GUID) of the report. This property will be returned only in GetReportsAsAdmin.

AdminTile

A Power BI tile returned by Admin APIs.

Name	Type	Description
colSpan	integer	The number of tile span columns
datasetId	string	The dataset ID. Available only for tiles created from a report or by using a dataset, such as Q&A tiles.
embedData	string	The embed data for the tile
embedUrl	string	The embed URL of the tile
id	string	The tile ID
reportId	string	The report ID. Available only for tiles created from a report.
rowSpan	integer	The number of tile span rows
title	string	The display name of the tile

AzureResource

A response detailing a user-owned Azure resource such as a Log Analytics workspace.

Name	Type	Description
id	string	An identifier for the resource within Power BI.
resourceGroup	string	The resource group within the subscription where the resource resides.
resourceName	string	The name of the resource.
subscriptionId	string	The Azure subscription where the resource resides.

DashboardUser

A Power BI user access right entry for a dashboard

Name	Type	Description
dashboardUserAccessRight	DashboardUserAccessRight	The access right that the 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	PrincipalType	The principal type
profile	ServicePrincipalProfile	A Power BI service principal profile. Only relevant for Power BI Embedded multi-tenancy solution.
userType	string	Type of the user.

DashboardUserAccessRight

The access right that the 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

DataflowUser

A Power BI user access right entry for a dataflow

Name	Type	Description
DataflowUserAccessRight	DataflowUserAccessRight	The access right that a 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	PrincipalType	The principal type
profile	ServicePrincipalProfile	A Power BI service principal profile. Only relevant for Power BI Embedded multi-tenancy solution.
userType	string	Type of the user.

DataflowUserAccessRight

The access right that a 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

DatasetQueryScaleOutSettings

Query scale-out settings of a dataset

Name	Type	Description
autoSyncReadOnlyReplicas	boolean	Whether the dataset automatically syncs read-only replicas
maxReadOnlyReplicas	integer	Maximum number of read-only replicas for the dataset (0-64, -1 for automatic number of replicas)

DatasetUser

A Power BI user access right entry for a dataset

Name	Type	Description
datasetUserAccessRight	DatasetUserAccessRight	The access right that the 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	PrincipalType	The principal type
profile	ServicePrincipalProfile	A Power BI service principal profile. Only relevant for Power BI Embedded multi-tenancy solution.
userType	string	Type of the user.

DatasetUserAccessRight

The access right that the user has for the dataset (permission level)

Name	Type	Description
None	string	Removes permission to the content in the dataset
Read	string	Grants Read access to the content in the dataset
ReadExplore	string	Grants Read and Explore access to the content in the dataset
ReadReshare	string	Grants Read and Reshare access to the content in the dataset
ReadReshareExplore	string	Grants Read, Reshare, and Explore access to the content in the dataset
ReadWrite	string	Grants Read and Write access to the content in the dataset
ReadWriteExplore	string	Grants Read, Write, and Explore access to the content in the dataset
ReadWriteReshare	string	Grants Read, Write, and Reshare access to the content in the dataset
ReadWriteReshareExplore	string	Grants Read, Write, Reshare, and Explore access to the content in the dataset

DefaultDatasetStorageFormat

The default dataset storage format in the group

Name	Type	Description
Large	string	Large dataset storage format
Small	string	Small dataset storage format

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	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 but isn't in sync with the encryption settings
NotSupported	string	Encryption isn't supported for this dataset
Unknown	string	The encryption status is unknown due to dataset corruption

GroupType

The group type

Name	Type	Description
Group	string	V1 version of shared workspace. This type of workspaces will be deprecated as Microsoft migrate all workspaces to latest version of shared workspace
Personal	string	Special type of workspace meant for SharePoint list and OneDrive integration
PersonalGroup	string	“My workspace”, also known as personal workspace
Workspace	string	Shared workspace or simple workspace used to share content with other users in the organization

GroupUser

A Power BI user with access to the 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	GroupUserAccessRight	The access right (permission level) that a user has on the workspace
identifier	string	Identifier of the principal
principalType	PrincipalType	The principal type
profile	ServicePrincipalProfile	A Power BI service principal profile. Only relevant for Power BI Embedded multi-tenancy solution.
userType	string	Type of the user.

GroupUserAccessRight

The access right (permission level) that a user has on the workspace

Name	Type	Description
Admin	string	Administrator rights to workspace content
Contributor	string	Read and explore (ReadExplore) access to workspace content
Member	string	Read, reshare and explore (ReadReshareExplore) access rights to workspace content
None	string	No access to workspace content
Viewer	string	Read-only (Read) access to workspace content

PrincipalType

The principal type

Name	Type	Description
App	string	Service principal type
Group	string	Group principal type
None	string	No principal type. Use for whole organization level access.
User	string	User principal type

ReportUser

A Power BI user access right entry for a 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	PrincipalType	The principal type
profile	ServicePrincipalProfile	A Power BI service principal profile. Only relevant for Power BI Embedded multi-tenancy solution.
reportUserAccessRight	ReportUserAccessRight	The access right that the user has for the report (permission level)
userType	string	Type of the user.

ReportUserAccessRight

The access right that the 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

ServicePrincipalProfile

A Power BI service principal profile. Only relevant for Power BI Embedded multi-tenancy solution.

Name	Type	Description
displayName	string	The service principal profile name
id	string	The service principal profile ID

Subscription

An email subscription for a Power BI item (such as a report or a dashboard)

Name	Type	Description
artifactDisplayName	string	The name of the subscribed Power BI item (such as a report or a dashboard)
artifactId	string	The ID of the subscribed Power BI item (such as a report or a dashboard)
artifactType	string	The type of Power BI item (for example a Report, Dashboard, or Dataset)
attachmentFormat	string	Format of the report attached in the email subscription
endDate	string	The end date and time of the email subscription
frequency	string	The frequency of the email subscription
id	string	The subscription ID
isEnabled	boolean	Whether the email subscription is enabled
linkToContent	boolean	Whether a subscription link exists in the email subscription
previewImage	boolean	Whether a screenshot of the report exists in the email subscription
startDate	string	The start date and time of the email subscription
subArtifactDisplayName	string	The page name of the subscribed Power BI item, if it's a report.
title	string	The app name
users	SubscriptionUser[]	The details of each email subscriber. When using the Get User Subscriptions As Admin API call, the returned value is an empty array (null). This property will be removed from the payload response in an upcoming release. You can retrieve subscription information on a Power BI report or dashboard by using the Get Report Subscriptions As Admin or Get Dashboard Subscriptions As Admin API calls.

SubscriptionUser

A Power BI email subscription user

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	PrincipalType	The principal type
profile	ServicePrincipalProfile	A Power BI service principal profile. Only relevant for Power BI Embedded multi-tenancy solution.
userType	string	Type of the user.

Workbook

A Power BI workbook

Name	Type	Description
datasetId	string	The ID of the dataset associated with a workbook. Only applies if the workbook has an associated dataset.
name	string	The workbook name