Datasets - Refresh Dataset

Service:

Power BI REST APIs

API Version:

v1.0

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

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/datasets/{datasetId}/refreshes

URI Parameters

Name	In	Required	Type	Description
datasetId	path	True	string	The dataset 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
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/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes

Sample Response

Status code:

202

x-ms-request-id: 03f22bb5-2e98-4ae8-8113-329bec3987b1
Location: https://api.powerbi.com/v1.0/myorg/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/03f22bb5-2e98-4ae8-8113-329bec3987b1

Example of refreshing one partition

Sample Request

POST https://api.powerbi.com/v1.0/myorg/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

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