Datasets - Refresh Dataset In Group

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

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

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

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

An array of objects to be processed
retryCount
  • integer

Number of times the operation will retry before failing
type

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
Request Body
{
  "notifyOption": "MailOnFailure",
  "retryCount": 3
}

Sample Response

Status code:
202 
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
Request Body
{
  "type": "full",
  "commitMode": "transactional",
  "objects": [
    {
      "table": "Customer",
      "partition": "Robert"
    }
  ],
  "applyRefreshPolicy": "false"
}

Sample Response

Status code:
200

Definitions

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
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

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

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

An array of objects to be processed
retryCount
  • integer

Number of times the operation will retry before failing
type

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