Upgrade - Upgrade Dataflows

Service:: Dataflow

API Version:: v1

Upgrades Gen1 dataflows in the specified workspace.

Note

Gen1 dataflow upgrade is currently in Preview (learn more).

This API supports long running operations (LRO).

Upgrades a caller-supplied batch of Gen1 dataflows to Dataflow Gen2 in place. Each successful upgrade preserves the dataflow identifier and workspace. The batch supports partial success. The operation returns the batch result synchronously when processing completes immediately, or returns an accepted response for asynchronous processing and makes the result available through the long-running operation.

Permissions

The caller must own each dataflow being upgraded or have the admin workspace role. Authorization is evaluated independently for each dataflow; an unauthorized dataflow is returned as a failed result row without failing the batch request.

Required Delegated Scopes

Dataflow.ReadWrite.All or Item.ReadWrite.All

Limitations

Each request must contain between 1 and 50 dataflows from the specified workspace.
The request body must not exceed 13 KiB (13,312 bytes), including whitespace.
Upgrades run in place and do not support cross-workspace targets.
Cancellation is not supported.

Microsoft Entra supported identities

This API supports the Microsoft identities listed in this section.

Identity	Support
User	Yes
Service principal and Managed identities	Yes

Interface

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/dataflows/gen1Upgrade

URI Parameters

Name	In	Required	Type	Description
workspaceId	path	True	string (uuid)	The workspace ID.

Request Body

Name	Required	Type	Description
dataflows	True	Gen1DataflowUpgradeTarget[]	The Gen1 dataflows to upgrade in the specified workspace.

Responses

Name	Type	Description
200 OK	DataflowUpgradeResult	Request completed successfully.
202 Accepted		Request accepted, the Gen1 dataflow upgrade is in progress. After the operation reaches a terminal state, retrieve the `DataflowUpgradeResult` payload by using the long running operations (LRO) APIs. Headers Location: string x-ms-operation-id: string Retry-After: integer
429 Too Many Requests	ErrorResponse	The service rate limit was exceeded. The server returns a `Retry-After` header indicating, in seconds, how long the client must wait before sending additional requests. Headers Retry-After: integer
Other Status Codes	ErrorResponse	Common error codes: WorkspaceNotFound - The specified workspace does not exist. InvalidItemsCount - The request contains fewer than 1 or more than 50 dataflows. InvalidParameter - A dataflow entry is malformed. InsufficientPrivileges - The caller does not have access to the workspace. FeatureNotAvailable - The operation is not enabled for the caller's tenant.

Examples

Upgrade Gen1 dataflows example

Sample request

HTTP

POST https://api.fabric.microsoft.com/v1/workspaces/afced311-0e76-4b74-9d59-6cdcbab44653/dataflows/gen1Upgrade

{
  "dataflows": [
    {
      "id": "6b1f3d2e-8a4c-4b6e-9f1a-2c3d4e5f6a7b"
    },
    {
      "id": "7c2a4e3f-9b5d-4c7f-a02b-3d4e5f6a7b8c"
    }
  ]
}

Sample response

Status code:: 200

{
  "summary": {
    "totalCount": 2,
    "succeededCount": 1,
    "failedCount": 1
  },
  "migrations": [
    {
      "dataflowId": "6b1f3d2e-8a4c-4b6e-9f1a-2c3d4e5f6a7b",
      "dataflowName": "Sales Ingestion (Gen1)",
      "targetDataflowName": "Sales Ingestion",
      "workspaceId": "afced311-0e76-4b74-9d59-6cdcbab44653",
      "workspaceName": "Test Workspace",
      "assessmentStatus": "ReadyToMigrate",
      "migrationStatus": "Succeeded",
      "migrationEndDateTime": "2026-08-19T10:15:42Z"
    },
    {
      "dataflowId": "7c2a4e3f-9b5d-4c7f-a02b-3d4e5f6a7b8c",
      "dataflowName": "Marketing Blend (Gen1)",
      "targetDataflowName": "Marketing Blend (Gen1)",
      "workspaceId": "afced311-0e76-4b74-9d59-6cdcbab44653",
      "workspaceName": "Test Workspace",
      "assessmentStatus": "NeedsAttention",
      "requiredActions": [
        {
          "status": "NeedsAttention",
          "code": "HasUnresolvedConnections",
          "message": "One or more data source connections could not be resolved. Recreate or rebind them before upgrading."
        }
      ],
      "migrationStatus": "Failed",
      "migrationError": {
        "errorCode": "DataflowRequiresChanges",
        "message": "The dataflow could not be upgraded because one or more data source connections could not be resolved.",
        "requestId": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "isRetriable": false
      }
    }
  ]
}

Status code:: 202

Location: https://api.fabric.microsoft.com/v1/operations/0acd697c-1550-43cd-b998-91bfbfbd47c6
x-ms-operation-id: 0acd697c-1550-43cd-b998-91bfbfbd47c6
Retry-After: 30

Definitions

Name	Description
DataflowMigration	The migration result for a Gen1 dataflow.
DataflowMigrationStatus	The outcome of a Gen1 dataflow migration. Additional DataflowMigrationStatus types may be added over time.
DataflowUpgradeReadinessStatus	The Gen1 dataflow upgrade readiness status. Additional DataflowUpgradeReadinessStatus types may be added over time.
DataflowUpgradeReasonCode	The reason for a Gen1 dataflow upgrade readiness result. Additional DataflowUpgradeReasonCode types may be added over time.
DataflowUpgradeRequiredAction	A change required before a Gen1 dataflow can be upgraded.
DataflowUpgradeResult	The result of a Gen1 dataflow upgrade batch.
DataflowUpgradeSummary	The roll-up counts for a Gen1 dataflow upgrade batch.
ErrorParameter	A structured parameter providing additional machine-readable context about an error.
ErrorRelatedResource	The error related resource details object.
ErrorResponse	The error response.
ErrorResponseDetails	The error response details.
Gen1DataflowUpgradeTarget	A Gen1 dataflow targeted for an in-place upgrade.
MigrationError	The failure detail for the dataflow migration. This property is present only when the migration status is `Failed`, and `isRetriable` is always included. The `requestId` contains the upgrade operation ID. The error code is one of `InsufficientPrivileges`, `DataflowNotFound`, `DataflowBusy`, `DataflowRequiresChanges`, `CapacityOrLicenseNotSupported`, or `UpgradeFailed`.
UpgradeGen1DataflowsRequest	The request payload for upgrading Gen1 dataflows.

DataflowMigration

Object

The migration result for a Gen1 dataflow.

Name	Type	Description
assessmentStatus	DataflowUpgradeReadinessStatus	The readiness verdict evaluated for the dataflow during the upgrade. This property does not report `UpgradeUnavailable`; a readiness result that predicts failure is reported as `NeedsAttention` because the migration status and migration error describe the actual outcome.
dataflowId	string (uuid)	The identifier of the dataflow, which is preserved by a successful in-place upgrade.
dataflowName	string	The source Gen1 dataflow display name.
migrationEndDateTime	string (date-time)	The time when the dataflow migration reached a terminal state. This property is omitted when the time is not available. When present, the value is in UTC, using the YYYY-MM-DDTHH:mm:ssZ format.
migrationError	MigrationError	The failure detail for the dataflow migration. This property is present only when the migration status is `Failed`, and `isRetriable` is always included. The `requestId` contains the upgrade operation ID. The error code is one of `InsufficientPrivileges`, `DataflowNotFound`, `DataflowBusy`, `DataflowRequiresChanges`, `CapacityOrLicenseNotSupported`, or `UpgradeFailed`.
migrationStatus	DataflowMigrationStatus	The migration outcome for the dataflow.
requiredActions	DataflowUpgradeRequiredAction[]	The changes required before the dataflow can be upgraded. This property is omitted when no changes are required.
targetDataflowName	string	The resulting Dataflow Gen2 display name, which may differ from the source display name.
workspaceId	string (uuid)	The identifier of the workspace containing the dataflow.
workspaceName	string	The display name of the workspace containing the dataflow.

DataflowMigrationStatus

Enumeration

The outcome of a Gen1 dataflow migration. Additional DataflowMigrationStatus types may be added over time.

Value	Description
Unknown	The migration outcome was not populated and indicates a service defect if returned.
Succeeded	The dataflow was upgraded successfully.
Failed	The dataflow failed to upgrade.

DataflowUpgradeReadinessStatus

Enumeration

The Gen1 dataflow upgrade readiness status. Additional DataflowUpgradeReadinessStatus types may be added over time.

Value	Description
Unknown	The readiness assessment could not be completed and should be reported for investigation.
ReadyToMigrate	The upgrade is expected to succeed without changes before or after the upgrade.
NeedsAttention	The upgrade is expected to succeed, but follow-up changes may be needed or the upgrade may adjust the dataflow automatically.
UpgradeUnavailable	The upgrade is expected to fail until the reported reasons are resolved.

DataflowUpgradeReasonCode

Enumeration

The reason for a Gen1 dataflow upgrade readiness result. Additional DataflowUpgradeReasonCode types may be added over time.

Value	Description
MightBeAccessedByDirectQuery	The dataflow might be accessed through DirectQuery.
HasByolAsStorage	The dataflow uses bring-your-own-lake storage.
HasIncrementalRefresh	The dataflow uses incremental refresh.
HasLinkedEntities	The dataflow has linked entities.
IsReferencedByLinkedEntities	The dataflow is referenced by linked entities in other dataflows.
ServiceThrottled	The readiness assessment was throttled and may succeed when retried later.
HasUnsupportedNameCharacters	The display name contains characters that are unsupported by Dataflow Gen2 and are sanitized during the upgrade.
DisplayNameAlreadyInUse	The sanitized display name is already in use and is prefixed during the upgrade.
ExceedsGen2QueryLimit	The dataflow has more load-enabled queries than Dataflow Gen2 supports.
HasUnresolvedConnections	One or more data source connections could not be resolved and must be recreated or rebound before the upgrade.
AssessmentUnavailable	The readiness assessment could not run and should be reported for investigation.

DataflowUpgradeRequiredAction

Object

A change required before a Gen1 dataflow can be upgraded.

Name	Type	Description
code	DataflowUpgradeReasonCode	The stable reason code identifying the required change.
message	string	The human-readable description of the required change.
status	DataflowUpgradeReadinessStatus	The readiness severity contributed by this required action.

DataflowUpgradeResult

Object

The result of a Gen1 dataflow upgrade batch.

Name	Type	Description
migrations	DataflowMigration[]	The migration result for each requested dataflow.
summary	DataflowUpgradeSummary	The roll-up counts for the upgrade batch.

DataflowUpgradeSummary

Object

The roll-up counts for a Gen1 dataflow upgrade batch.

Name	Type	Description
failedCount	integer (int32)	The number of dataflows that failed to upgrade.
succeededCount	integer (int32)	The number of dataflows that were upgraded successfully.
totalCount	integer (int32)	The total number of dataflows in the request.

ErrorParameter

Object

A structured parameter providing additional machine-readable context about an error.

Name	Type	Description
message	string	A human-readable description of the parameter's meaning.
name	string	The parameter identifier.
value	string	The parameter value.

ErrorRelatedResource

Object

The error related resource details object.

Name	Type	Description
resourceId	string	The resource ID that's involved in the error.
resourceType	string	The type of the resource that's involved in the error.

ErrorResponse

Object

The error response.

Name	Type	Description
errorCode	string	A specific identifier that provides information about an error condition, allowing for standardized communication between our service and its users.
isRetriable	boolean	When true, the request can be retried. Use the `Retry-After` response header to determine the delay, if available.
message	string	A human readable representation of the error.
moreDetails	ErrorResponseDetails[]	List of additional error details.
parameters	ErrorParameter[]	Structured parameters providing additional machine-readable context about the error.
relatedResource	ErrorRelatedResource	The error related resource details.
requestId	string (uuid)	ID of the request associated with the error.

ErrorResponseDetails

Object

The error response details.

Name	Type	Description
errorCode	string	A specific identifier that provides information about an error condition, allowing for standardized communication between our service and its users.
message	string	A human readable representation of the error.
parameters	ErrorParameter[]	Structured parameters providing additional machine-readable context about the error.
relatedResource	ErrorRelatedResource	The error related resource details.

Gen1DataflowUpgradeTarget

Object

A Gen1 dataflow targeted for an in-place upgrade.

Name	Type	Description
id	string (uuid)	The identifier of the Gen1 dataflow to upgrade. The dataflow must belong to the specified workspace.

MigrationError

Object

The failure detail for the dataflow migration. This property is present only when the migration status is Failed, and isRetriable is always included. The requestId contains the upgrade operation ID. The error code is one of InsufficientPrivileges, DataflowNotFound, DataflowBusy, DataflowRequiresChanges, CapacityOrLicenseNotSupported, or UpgradeFailed.

Name	Type	Description
errorCode	string	A specific identifier that provides information about an error condition, allowing for standardized communication between our service and its users.
isRetriable	boolean	When true, the request can be retried. Use the `Retry-After` response header to determine the delay, if available.
message	string	A human readable representation of the error.
moreDetails	ErrorResponseDetails[]	List of additional error details.
parameters	ErrorParameter[]	Structured parameters providing additional machine-readable context about the error.
relatedResource	ErrorRelatedResource	The error related resource details.
requestId	string (uuid)	ID of the request associated with the error.

UpgradeGen1DataflowsRequest

Object

The request payload for upgrading Gen1 dataflows.

Name	Type	Description
dataflows	Gen1DataflowUpgradeTarget[]	The Gen1 dataflows to upgrade in the specified workspace.