Datasets - Refresh Dataset In Group

Triggers a refresh for the specified dataset from the specified workspace. An enhanced refresh is triggered only if a request payload other than notifyOption is set.

Permissions

This API call can be called by a service principal profile. For more information see: Service principal profiles in Power BI Embedded.

Required Scope

Dataset.ReadWrite.All

Limitations

  • For Shared capacities, a maximum of eight requests per day, including refreshes executed by using scheduled refresh, can be initiated.
  • For Shared capacities, only notifyOption can be specified in the request body.
  • Enhanced refresh is not supported for shared capacities.
  • For enhanced refresh, notifyOption is not required and must be excluded from the request body. However, one or more parameters other than notifyOption are required.
  • For Premium capacities, the maximum requests per day is only limited by the available resources in the capacity. If available resources are overloaded, refreshes are throttled until the load is reduced. The refresh will fail if throttling exceeds 1 hour.

POST https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes

URI Parameters

Name In Required Type Description
datasetId
path True

string

The dataset ID

groupId
path True

string

uuid

The workspace ID

Request Body

Name Required Type Description
notifyOption True

NotifyOption

Mail notification options. This parameter is not applicable to enhanced refreshes or API operations with a service principal.

applyRefreshPolicy

boolean

Determine if the policy is applied or not

commitMode

DatasetCommitMode

Determines if objects will be committed in batches or only when complete

effectiveDate

string

If an incremental refresh policy is applied, the effectiveDate parameter overrides the current date.

maxParallelism

integer

The maximum number of threads on which to run parallel processing commands

objects

DatasetRefreshObjects[]

An array of objects to be processed

retryCount

integer

Number of times the operation will retry before failing. Temporary internal errors may trigger a retry of the refresh, even when this parameter is set to 0.

type

DatasetRefreshType

The type of processing to perform

Responses

Name Type Description
202 Accepted

Accepted

Headers

  • x-ms-request-id: string
  • Location: string

Examples

Example of refreshing a dataset
Example of refreshing one partition

Example of refreshing a dataset

Sample request

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes
{
  "notifyOption": "MailOnFailure",
  "retryCount": 3
}

Sample response

x-ms-request-id: 87f31ef7-1e3a-4006-9b0b-191693e79e9e
Location: https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/87f31ef7-1e3a-4006-9b0b-191693e79e9e

Example of refreshing one partition

Sample request

POST https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes
{
  "type": "full",
  "commitMode": "transactional",
  "objects": [
    {
      "table": "Customer",
      "partition": "Robert"
    }
  ],
  "applyRefreshPolicy": "false"
}

Sample response

Definitions

Name Description
DatasetCommitMode

Determines if objects will be committed in batches or only when complete

DatasetRefreshObjects

Power BI dataset refresh target

DatasetRefreshRequest

Power BI dataset refresh request

DatasetRefreshType

The type of processing to perform

NotifyOption

Mail notification options

DatasetCommitMode

Determines if objects will be committed in batches or only when complete

Name Type Description
PartialBatch

string

Commit the refresh operation in batches. When utilizing partialBatch mode, the refresh operation does not occur within a transaction. Consequently, each command will be committed individually, and in the event of a failure, the model may end up in a state where only a subset of the data is loaded, or the table is left empty. If you desire to guarantee the preservation of previous data in case of a failure, you should execute the operation with commitMode = transactional.

Transactional

string

Commit the whole refresh operation as a transaction

DatasetRefreshObjects

Power BI dataset refresh target

Name Type Description
partition

string

Partition to refresh

table

string

Table to refresh

DatasetRefreshRequest

Power BI dataset refresh request

Name Type Description
applyRefreshPolicy

boolean

Determine if the policy is applied or not

commitMode

DatasetCommitMode

Determines if objects will be committed in batches or only when complete

effectiveDate

string

If an incremental refresh policy is applied, the effectiveDate parameter overrides the current date.

maxParallelism

integer

The maximum number of threads on which to run parallel processing commands

notifyOption

NotifyOption

Mail notification options. This parameter is not applicable to enhanced refreshes or API operations with a service principal.

objects

DatasetRefreshObjects[]

An array of objects to be processed

retryCount

integer

Number of times the operation will retry before failing. Temporary internal errors may trigger a retry of the refresh, even when this parameter is set to 0.

type

DatasetRefreshType

The type of processing to perform

DatasetRefreshType

The type of processing to perform

Name Type Description
Automatic

string

If the object needs to be refreshed and recalculated, refresh and recalculate the object and all its dependents. Applies if the partition is in a state other than Ready.

Calculate

string

Recalculate this object and all its dependents, but only if needed. This value doesn't force recalculation, except for volatile formulas.

ClearValues

string

Clear values in this object and all its dependents

DataOnly

string

Refresh data in this object and clear all dependents

Defragment

string

Defragment the data in the specified table. As data is added to or removed from a table, the dictionaries of each column can become polluted with values that no longer exist in the actual column values. The defragment option will clean up the values in the dictionaries that are no longer used.

Full

string

For all partitions in the specified partition, table, or database, refresh data and recalculate all dependents. For a calculation partition, recalculate the partition and all its dependents.

NotifyOption

Mail notification options

Name Type Description
MailOnCompletion

string

A mail notification indicating success or failure will be sent on refresh completion

MailOnFailure

string

A mail notification will be sent on refresh failure

NoNotification

string

No notification will be sent