{ "swagger": "2.0", "info": { "title": "Dataflow REST APIs", "version": "v1" }, "schemes": [ "https" ], "host": "api.fabric.microsoft.com", "basePath": "/v1", "paths": { "/workspaces/{workspaceId}/dataflows": { "get": { "summary": "Returns a list of Dataflows from the specified workspace.", "description": "This API supports [pagination](/rest/api/fabric/articles/pagination).\n\n## Permissions\n\n The caller must have a *viewer* workspace role. \n\n## Required Delegated Scopes\n\nWorkspace.Read.All or Workspace.ReadWrite.All\n\n## Microsoft Entra supported identities\n\nThis API supports the Microsoft [identities](/rest/api/fabric/articles/identity-support) listed in this section.\n\n| Identity | Support |\n|-|-|\n| User | Yes |\n| [Service principal](/entra/identity-platform/app-objects-and-service-principals#service-principal-object) and [Managed identities](/entra/identity/managed-identities-azure-resources/overview) | Yes |\n\n## Interface", "tags": [ "Items" ], "operationId": "Items_ListDataflows", "x-ms-pageable": { "nextLinkName": "continuationUri" }, "produces": [ "application/json" ], "parameters": [ { "in": "path", "name": "workspaceId", "description": "The workspace ID.", "type": "string", "format": "uuid", "required": true }, { "in": "query", "name": "recursive", "description": "Lists items in a folder and its nested folders, or just a folder only. True - All items in the folder and its nested folders are listed, False - Only items in the folder are listed. The default value is true.", "type": "boolean", "required": false }, { "in": "query", "name": "rootFolderId", "description": "This parameter allows users to filter items based on a specific root folder. If not provided, the workspace is used as the root folder.", "type": "string", "format": "uuid", "required": false }, { "in": "query", "name": "continuationToken", "description": "A token for retrieving the next page of results.", "type": "string", "required": false } ], "responses": { "200": { "description": "Request completed successfully.", "schema": { "$ref": "./definitions.json#/definitions/Dataflows" } }, "429": { "description": "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.", "x-ms-error-response": true, "headers": { "Retry-After": { "type": "integer", "description": "The number of seconds to wait before retrying the request." } }, "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } }, "default": { "description": "Common error codes:\n\n* InvalidItemType - Invalid item type.", "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } } }, "x-ms-examples": { "List Dataflows in workspace example": { "$ref": "./examples/ListDataflowsInWorkspace.json" } } }, "post": { "summary": "Creates a Dataflow in the specified workspace.", "description": "This API supports [long running operations (LRO)](/rest/api/fabric/articles/long-running-operation).\n\n To create Dataflow with a public definition, refer to [Dataflow](/rest/api/fabric/articles/item-management/definitions/dataflow-definition) article. \n\n ## Permissions \n The caller must have a *contributor* workspace role. \n\n## Required Delegated Scopes\n\n Dataflow.ReadWrite.All or Item.ReadWrite.All \n\n## Limitations \n- To create a Dataflow the workspace must be on a supported Fabric capacity. For more information see: [Microsoft Fabric license types](/fabric/enterprise/licenses#microsoft-fabric-license-types).\n\n## Microsoft Entra supported identities\n\nThis API supports the Microsoft [identities](/rest/api/fabric/articles/identity-support) listed in this section.\n\n| Identity | Support |\n|-|-|\n| User | Yes |\n| [Service principal](/entra/identity-platform/app-objects-and-service-principals#service-principal-object) and [Managed identities](/entra/identity/managed-identities-azure-resources/overview) | Yes |\n\n## Interface", "tags": [ "Items" ], "operationId": "Items_CreateDataflow", "consumes": [ "application/json" ], "produces": [ "application/json" ], "x-ms-fabric-sdk-long-running-operation": true, "parameters": [ { "in": "path", "name": "workspaceId", "description": "The workspace ID.", "type": "string", "format": "uuid", "required": true }, { "in": "body", "name": "createDataflowRequest", "description": "Create item request payload.", "schema": { "$ref": "./definitions.json#/definitions/CreateDataflowRequest" }, "required": true } ], "responses": { "201": { "description": "Successfully created", "schema": { "$ref": "./definitions.json#/definitions/Dataflow" } }, "202": { "description": "Request accepted, Dataflow provisioning in progress.", "headers": { "Location": { "description": "The URL of the operation status, which can be used to track the operation state.", "type": "string" }, "x-ms-operation-id": { "description": "The operation ID which can be used with long running operations (LRO) APIs to track the operation state and get the result.", "type": "string", "format": "uuid" }, "Retry-After": { "type": "integer", "description": "The number of seconds to wait before retrying the request." } } }, "429": { "description": "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.", "x-ms-error-response": true, "headers": { "Retry-After": { "type": "integer", "description": "The number of seconds to wait before retrying the request." } }, "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } }, "default": { "description": "Common error codes:\n\n* InvalidItemType - Item type is invalid\n\n* ItemDisplayNameAlreadyInUse - Item display name is already used.\n\n* CorruptedPayload - The provided payload is corrupted.", "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } } }, "x-ms-examples": { "Create a Dataflow example": { "$ref": "./examples/CreateDataflowWithoutDefinition.json" }, "Create a Dataflow with public definition example": { "$ref": "./examples/CreateDataflow.json" } } } }, "/workspaces/{workspaceId}/dataflows/{dataflowId}": { "get": { "summary": "Returns properties of the specified Dataflow.", "description": "## Permissions\n\n The caller must have *read* permissions for the dataflow. \n\n## Required Delegated Scopes\n\n Dataflow.Read.All or Dataflow.ReadWrite.All or Item.Read.All or Item.ReadWrite.All\n\n## Microsoft Entra supported identities\n\nThis API supports the Microsoft [identities](/rest/api/fabric/articles/identity-support) listed in this section.\n\n| Identity | Support |\n|-|-|\n| User | Yes |\n| [Service principal](/entra/identity-platform/app-objects-and-service-principals#service-principal-object) and [Managed identities](/entra/identity/managed-identities-azure-resources/overview) | Yes |\n\n## Interface", "tags": [ "Items" ], "operationId": "Items_GetDataflow", "produces": [ "application/json" ], "parameters": [ { "in": "path", "name": "workspaceId", "description": "The workspace ID.", "type": "string", "format": "uuid", "required": true }, { "in": "path", "name": "dataflowId", "description": "The Dataflow ID.", "type": "string", "format": "uuid", "required": true } ], "responses": { "200": { "description": "Request completed successfully.", "schema": { "$ref": "./definitions.json#/definitions/Dataflow" } }, "429": { "description": "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.", "x-ms-error-response": true, "headers": { "Retry-After": { "type": "integer", "description": "The number of seconds to wait before retrying the request." } }, "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } }, "default": { "description": "Common error codes:\n\n* ItemNotFound - The requested item was not found.", "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } } }, "x-ms-examples": { "Get a Dataflow example": { "$ref": "./examples/GetDataflow.json" } } }, "patch": { "summary": "Updates the properties of the specified Dataflow.", "description": "## Permissions\n\n The caller must have *read and write* permissions for the dataflow.\n\n## Required Delegated Scopes\n\n Dataflow.ReadWrite.All or Item.ReadWrite.All\n\n## Microsoft Entra supported identities\n\nThis API supports the Microsoft [identities](/rest/api/fabric/articles/identity-support) listed in this section.\n\n| Identity | Support |\n|-|-|\n| User | Yes |\n| [Service principal](/entra/identity-platform/app-objects-and-service-principals#service-principal-object) and [Managed identities](/entra/identity/managed-identities-azure-resources/overview) | Yes |\n\n## Interface", "tags": [ "Items" ], "operationId": "Items_UpdateDataflow", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "in": "path", "name": "workspaceId", "description": "The workspace ID.", "type": "string", "format": "uuid", "required": true }, { "in": "path", "name": "dataflowId", "description": "The Dataflow ID.", "type": "string", "format": "uuid", "required": true }, { "in": "body", "name": "updateDataflowRequest", "description": "Update Dataflow request payload.", "schema": { "$ref": "./definitions.json#/definitions/UpdateDataflowRequest" }, "required": true } ], "responses": { "200": { "description": "Request completed successfully.", "schema": { "$ref": "./definitions.json#/definitions/Dataflow" } }, "429": { "description": "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.", "x-ms-error-response": true, "headers": { "Retry-After": { "type": "integer", "description": "The number of seconds to wait before retrying the request." } }, "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } }, "default": { "description": "Common error codes:\n\n* ItemNotFound - The requested item was not found. \n\n* InvalidRequest - Invalid update request.", "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } } }, "x-ms-examples": { "Update a Dataflow example": { "$ref": "./examples/UpdateDataflow.json" } } }, "delete": { "summary": "Deletes the specified Dataflow.", "description": "## Permissions\n\n The caller must have *write* permissions for the dataflow. \n\n## Required Delegated Scopes\n\n Dataflow.ReadWrite.All or Item.ReadWrite.All\n\n## Microsoft Entra supported identities\n\nThis API supports the Microsoft [identities](/rest/api/fabric/articles/identity-support) listed in this section.\n\n| Identity | Support |\n|-|-|\n| User | Yes |\n| [Service principal](/entra/identity-platform/app-objects-and-service-principals#service-principal-object) and [Managed identities](/entra/identity/managed-identities-azure-resources/overview) | Yes |\n\n## Interface", "tags": [ "Items" ], "operationId": "Items_DeleteDataflow", "produces": [ "application/json" ], "parameters": [ { "in": "path", "name": "workspaceId", "description": "The workspace ID.", "type": "string", "format": "uuid", "required": true }, { "in": "path", "name": "dataflowId", "description": "The Dataflow ID.", "type": "string", "format": "uuid", "required": true }, { "in": "query", "name": "hardDelete", "description": "Specifies whether to perform a hard delete. When set to `true`, the item is permanently deleted and cannot be recovered. When set to `false` or not specified, the item is soft-deleted if the item type supports it.", "type": "boolean", "required": false } ], "responses": { "200": { "description": "Request completed successfully." }, "429": { "description": "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.", "x-ms-error-response": true, "headers": { "Retry-After": { "type": "integer", "description": "The number of seconds to wait before retrying the request." } }, "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } }, "default": { "description": "Common error codes:\n\n* ItemNotFound - The requested item was not found.\n\n* InsufficientWorkspaceRole - User doesn't have sufficient workspace role.\n\n* FeatureNotAvailable - This could be due to the soft deletion feature not being available.\n\n* UnsupportedItemType - This could be due to the soft deletion feature not supported by the requested item type.\n\n* TenantSwitchDisabled - This could be due to the soft deletion feature being disabled by the tenant admin.\n\n* InvalidTargetItemStateForSoftDeletion - The item is in invalid states for soft deletion.\n\n* InvalidParentItemStateForSoftDeletion - The item's parent item is not in Active state.", "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } } }, "x-ms-examples": { "Delete a Dataflow example": { "$ref": "./examples/DeleteDataflow.json" }, "Hard delete a Dataflow example": { "$ref": "./examples/HardDeleteDataflow.json" } } } }, "/workspaces/{workspaceId}/dataflows/{dataflowId}/getDefinition": { "post": { "summary": "Returns the specified Dataflow public definition.", "description": "This API supports [long running operations (LRO)](/rest/api/fabric/articles/long-running-operation).\n\nWhen you get a Dataflow's public definition, the sensitivity label is not a part of the definition.\n\n## Permissions\n\n The caller must have *read and write* permissions for the dataflow.\n## Required Delegated Scopes\n\n Dataflow.ReadWrite.All or Item.ReadWrite.All\n\n## Microsoft Entra supported identities\n\nThis API supports the Microsoft [identities](/rest/api/fabric/articles/identity-support) listed in this section.\n\n| Identity | Support |\n|-|-|\n| User | Yes |\n| [Service principal](/entra/identity-platform/app-objects-and-service-principals#service-principal-object) and [Managed identities](/entra/identity/managed-identities-azure-resources/overview) | Yes |\n\n## Interface", "tags": [ "Items" ], "operationId": "Items_GetDataflowDefinition", "produces": [ "application/json" ], "x-ms-fabric-sdk-long-running-operation": true, "parameters": [ { "in": "path", "name": "workspaceId", "description": "The workspace ID.", "type": "string", "format": "uuid", "required": true }, { "in": "path", "name": "dataflowId", "description": "The Dataflow ID.", "type": "string", "format": "uuid", "required": true }, { "in": "query", "name": "format", "description": "The format of the dataflow public definition.", "type": "string", "required": false } ], "responses": { "200": { "description": "Request completed successfully.", "schema": { "$ref": "./definitions.json#/definitions/DataflowDefinitionResponse" } }, "202": { "description": "Request accepted. Retrieving the definition is in progress.", "headers": { "Location": { "description": "The URL of the operation status, which can be used to track the operation state.", "type": "string" }, "x-ms-operation-id": { "description": "The operation ID which can be used with long running operations (LRO) APIs to track the operation state and get the result.", "type": "string", "format": "uuid" }, "Retry-After": { "type": "integer", "description": "The number of seconds to wait before retrying the request." } } }, "429": { "description": "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.", "x-ms-error-response": true, "headers": { "Retry-After": { "type": "integer", "description": "The number of seconds to wait before retrying the request." } }, "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } }, "default": { "description": "Common error codes:\n\n* OperationNotSupportedForItem - Operation not supported for requested item.", "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } } }, "x-ms-examples": { "Get a Dataflow public definition example": { "$ref": "./examples/GetDataflowDefinition.json" } } } }, "/workspaces/{workspaceId}/dataflows/{dataflowId}/updateDefinition": { "post": { "summary": "Overrides the definition for the specified Dataflow.", "description": "This API supports [long running operations (LRO)](/rest/api/fabric/articles/long-running-operation).\n\n \nUpdating the Dataflow's definition, does not affect its sensitivity label. \n\n## Permissions\n\n The caller must have *read and write* permissions for the dataflow. \n## Required Delegated Scopes\n\n Dataflow.ReadWrite.All or Item.ReadWrite.All\n\n## Microsoft Entra supported identities\n\nThis API supports the Microsoft [identities](/rest/api/fabric/articles/identity-support) listed in this section.\n\n| Identity | Support |\n|-|-|\n| User | Yes |\n| [Service principal](/entra/identity-platform/app-objects-and-service-principals#service-principal-object) and [Managed identities](/entra/identity/managed-identities-azure-resources/overview) | Yes |\n\n## Interface", "tags": [ "Items" ], "operationId": "Items_UpdateDataflowDefinition", "produces": [ "application/json" ], "x-ms-fabric-sdk-long-running-operation": true, "parameters": [ { "in": "path", "name": "workspaceId", "description": "The workspace ID.", "type": "string", "format": "uuid", "required": true }, { "in": "path", "name": "dataflowId", "description": "The Dataflow ID.", "type": "string", "format": "uuid", "required": true }, { "in": "query", "name": "updateMetadata", "description": "When set to true and the .platform file is provided as part of the definition, the item's metadata is updated using the metadata in the .platform file", "type": "boolean", "required": false }, { "in": "body", "name": "updateDataflowDefinitionRequest", "description": "Update Dataflow definition request payload.", "schema": { "$ref": "./definitions.json#/definitions/UpdateDataflowDefinitionRequest" }, "required": true } ], "responses": { "200": { "description": "Request completed successfully." }, "202": { "description": "Request accepted. Update definition is in progress.", "headers": { "Location": { "description": "The URL of the operation status, which can be used to track the operation state.", "type": "string" }, "x-ms-operation-id": { "description": "The operation ID which can be used with long running operations (LRO) APIs to track the operation state and get the result.", "type": "string", "format": "uuid" }, "Retry-After": { "type": "integer", "description": "The number of seconds to wait before retrying the request." } } }, "429": { "description": "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.", "x-ms-error-response": true, "headers": { "Retry-After": { "type": "integer", "description": "The number of seconds to wait before retrying the request." } }, "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } }, "default": { "description": "Common error codes:\n\n* OperationNotSupportedForItem - Operation not supported for requested item. \n\n* CorruptedPayload - The provided payload is corrupted.", "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } } }, "x-ms-examples": { "Update a Dataflow public definition example": { "$ref": "./examples/UpdateDataflowDefinition.json" } } } }, "/workspaces/{workspaceId}/dataflows/{dataflowId}/parameters": { "get": { "summary": "Retrieves all parameters defined in the specified Dataflow.", "description": "## Permissions\n\nThe caller must have *read* permissions for the dataflow.\n\n## Required Delegated Scopes\n\nDataflow.Read.All or Dataflow.ReadWrite.All or Item.Read.All or Item.ReadWrite.All\n\n## Microsoft Entra supported identities\n\nThis API supports the Microsoft [identities](/rest/api/fabric/articles/identity-support) listed in this section.\n\n| Identity | Support |\n|-|-|\n| User | Yes |\n| [Service principal](/entra/identity-platform/app-objects-and-service-principals#service-principal-object) and [Managed identities](/entra/identity/managed-identities-azure-resources/overview) | Yes |\n\n## Interface", "tags": [ "Items" ], "operationId": "Items_DiscoverDataflowParameters", "x-ms-pageable": { "nextLinkName": "continuationUri" }, "produces": [ "application/json" ], "parameters": [ { "in": "path", "name": "workspaceId", "description": "The workspace ID.", "type": "string", "format": "uuid", "required": true }, { "in": "path", "name": "dataflowId", "description": "The Dataflow ID.", "type": "string", "format": "uuid", "required": true }, { "in": "query", "name": "continuationToken", "description": "A token for retrieving the next page of results.", "type": "string", "required": false } ], "responses": { "200": { "description": "Request completed successfully.", "schema": { "$ref": "./definitions.json#/definitions/DataflowParameters" } }, "429": { "description": "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.", "x-ms-error-response": true, "headers": { "Retry-After": { "type": "integer", "description": "The number of seconds to wait before retrying the request." } }, "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } }, "default": { "description": "Common error codes:\n\n* ItemNotFound - The requested item was not found \n\n* DataflowNotParametricError - The requested dataflow is not parametric", "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } } }, "x-ms-examples": { "Get Dataflow Parameters example": { "$ref": "./examples/DiscoverDataflowParameters.json" } } } }, "/workspaces/{workspaceId}/dataflows/{dataflowId}/jobs/execute/schedules": { "post": { "summary": "Create a new execute schedule for a dataflow. A dataflow can create maximum 20 schedulers.", "description": "> [!NOTE]\n> This API is part of a Preview release and is provided for evaluation and development purposes only. It may change based on feedback and is not recommended for production use.\n\n## Permissions\n\n- The caller must have a *member* or higher workspace role.\n- Access to all connections used by the dataflow\n\n## Required Delegated Scopes: \n\nDataflow.Execute.All and Dataflow.ReadWrite.All\n\n## Microsoft Entra supported identities\n\nThis API supports the Microsoft [identities](/rest/api/fabric/articles/identity-support) listed in this section.\n\n| Identity | Support |\n|-|-|\n| User | Yes |\n| [Service principal](/entra/identity-platform/app-objects-and-service-principals#service-principal-object) and [Managed identities](/entra/identity/managed-identities-azure-resources/overview) | No |\n\n## Interface", "tags": [ "BackgroundJobs" ], "operationId": "BackgroundJobs_ScheduleExecute", "produces": [ "application/json" ], "parameters": [ { "in": "path", "name": "workspaceId", "description": "The workspace ID.", "type": "string", "format": "uuid", "required": true }, { "in": "path", "name": "dataflowId", "description": "The item ID.", "type": "string", "format": "uuid", "required": true }, { "in": "body", "name": "createScheduleRequest", "description": "A dataflow execute schedule create request.", "schema": { "$ref": "./definitions.json#/definitions/CreateDataflowExecuteScheduleRequest" }, "required": true } ], "responses": { "201": { "description": "Successfully create the schedule.", "headers": { "Location": { "description": "The URL of the newly created schedule.", "type": "string" } }, "schema": { "$ref": "./definitions.json#/definitions/DataflowSchedule" } }, "429": { "description": "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.", "x-ms-error-response": true, "headers": { "Retry-After": { "type": "integer", "description": "The number of seconds to wait before retrying the request." } }, "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } }, "default": { "description": "Common error codes:\n\n* InsufficientPrivileges - The caller does not have sufficient permissions to access the item\n\n* ItemNotFound - Requested item id not found\n\n* ScheduleExceedsLimit - The number of created schedules for the item exceeds the limit", "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } } }, "x-ms-examples": { "Create dataflow Execute schedule example": { "$ref": "./examples/CreateDataflowExecuteSchedule.json" } } } }, "/workspaces/{workspaceId}/dataflows/{dataflowId}/jobs/applyChanges/schedules": { "post": { "summary": "Create a new apply changes schedule for a dataflow. A dataflow can create maximum 20 schedulers.", "description": "> [!NOTE]\n> This API is part of a Preview release and is provided for evaluation and development purposes only. It may change based on feedback and is not recommended for production use.\n\n## Required Delegated Scopes: \n\nDataflow.Execute.All and Dataflow.ReadWrite.All\n\n## Microsoft Entra supported identities\n\nThis API supports the Microsoft [identities](/rest/api/fabric/articles/identity-support) listed in this section.\n\n| Identity | Support |\n|-|-|\n| User | Yes |\n| [Service principal](/entra/identity-platform/app-objects-and-service-principals#service-principal-object) and [Managed identities](/entra/identity/managed-identities-azure-resources/overview) | No |\n\n## Interface", "tags": [ "BackgroundJobs" ], "operationId": "BackgroundJobs_ScheduleApplyChanges", "produces": [ "application/json" ], "parameters": [ { "in": "path", "name": "workspaceId", "description": "The workspace ID.", "type": "string", "format": "uuid", "required": true }, { "in": "path", "name": "dataflowId", "description": "The item ID.", "type": "string", "format": "uuid", "required": true }, { "in": "body", "name": "createScheduleRequest", "description": "A apply changes dataflow schedule create request.", "schema": { "$ref": "./definitions.json#/definitions/CreateDataflowApplyChangesScheduleRequest" }, "required": true } ], "responses": { "201": { "description": "Successfully create the schedule.", "headers": { "Location": { "description": "The URL of the newly created schedule.", "type": "string" } }, "schema": { "$ref": "./definitions.json#/definitions/DataflowSchedule" } }, "429": { "description": "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.", "x-ms-error-response": true, "headers": { "Retry-After": { "type": "integer", "description": "The number of seconds to wait before retrying the request." } }, "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } }, "default": { "description": "Common error codes:\n\n* InsufficientPrivileges - The caller does not have sufficient permissions to access the item\n\n* ItemNotFound - Requested item id not found\n\n* ScheduleExceedsLimit - The number of created schedules for the item exceeds the limit", "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } } }, "x-ms-examples": { "Create dataflow ApplyChanges schedule example": { "$ref": "./examples/CreateDataflowApplyChangesSchedule.json" } } } }, "/workspaces/{workspaceId}/dataflows/{dataflowId}/jobs/execute/instances": { "post": { "summary": "Run on-demand execute job instance.", "description": "> [!NOTE]\n> This API is part of a Preview release and is provided for evaluation and development purposes only. It may change based on feedback and is not recommended for production use.\n> The URL for this API has been updated to include the job type as part of the path, replacing the previous use of a query parameter. For backward compatibility, invocations using the query parameter are still supported.\n\n## Permissions\n\n- The caller must have a *member* or higher workspace role.\n- Access to all connections used by the dataflow\n\n## Required Delegated Scopes\n\n For dataflows APIs use these scope types: \n- Specific scope: Dataflow.Execute.All \n\n for more information about scopes, see: [scopes article](/rest/api/fabric/articles/scopes).\n\n## Microsoft Entra supported identities\n\nThis API supports the Microsoft [identities](/rest/api/fabric/articles/identity-support) listed in this section.\n\n| Identity | Support |\n|-|-|\n| User | Yes |\n| [Service principal](/entra/identity-platform/app-objects-and-service-principals#service-principal-object) and [Managed identities](/entra/identity/managed-identities-azure-resources/overview) | No |\n\n## Interface", "tags": [ "BackgroundJobs" ], "operationId": "BackgroundJobs_RunOnDemandExecute", "produces": [ "application/json" ], "parameters": [ { "in": "path", "name": "workspaceId", "description": "The workspace ID.", "type": "string", "format": "uuid", "required": true }, { "in": "path", "name": "dataflowId", "description": "The dataflow ID.", "type": "string", "format": "uuid", "required": true }, { "in": "body", "name": "runOnDemandItemJobRequest", "description": "Run on-demand item job request payload.", "schema": { "$ref": "./definitions.json#/definitions/RunOnDemandDataflowExecuteJobRequest" }, "required": false } ], "responses": { "202": { "description": "Request accepted, job execution is in progress.\n\n---\n**Headers:**\n\n**Location** `string` - The URL to the job instance resource.\n\n**Retry-After** `integer` - The number of seconds the client should wait before polling the job status for the first time. Clients must use this value to determine when to check the job status and should wait at least this many seconds before the first status poll." }, "429": { "description": "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.", "x-ms-error-response": true, "headers": { "Retry-After": { "type": "integer", "description": "The number of seconds to wait before retrying the request." } }, "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } }, "default": { "description": "Common error codes:\n\n* InsufficientPrivileges - The caller does not have sufficient permissions to run job instance.\n\n* InvalidJobType - The requested job type is invalid.\n\n* TooManyRequestsForJobs - The caller requests too many on-demand job requests.\n\n* ItemNotFound - Requested item ID not found.", "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } } }, "x-ms-examples": { "Run dataflow Execute job instance with no request body example": { "$ref": "./examples/RunOnDemandDataflowExecuteJob.json" }, "Run dataflow Execute job instance with request body containing parameters example": { "$ref": "./examples/RunOnDemandDataflowExecuteJobWithParameters.json" } } } }, "/workspaces/{workspaceId}/dataflows/{dataflowId}/jobs/applyChanges/instances": { "post": { "summary": "Run on-demand apply changes job instance.", "description": "> [!NOTE]\n> This API is part of a Preview release and is provided for evaluation and development purposes only. It may change based on feedback and is not recommended for production use.\n\n> [!NOTE]\n> The URL for this API has been updated to include the job type as part of the path, replacing the previous use of a query parameter. For backward compatibility, invocations using the query parameter are still supported.\n\n## Required Delegated Scopes\n\n For dataflows APIs use these scope types: \n- Specific scope: Dataflow.Execute.All \n\n for more information about scopes, see: [scopes article](/rest/api/fabric/articles/scopes).\n\n## Microsoft Entra supported identities\n\nThis API supports the Microsoft [identities](/rest/api/fabric/articles/identity-support) listed in this section.\n\n| Identity | Support |\n|-|-|\n| User | Yes |\n| [Service principal](/entra/identity-platform/app-objects-and-service-principals#service-principal-object) and [Managed identities](/entra/identity/managed-identities-azure-resources/overview) | No |\n\n## Interface", "tags": [ "BackgroundJobs" ], "operationId": "BackgroundJobs_RunOnDemandApplyChanges", "produces": [ "application/json" ], "parameters": [ { "in": "path", "name": "workspaceId", "description": "The workspace ID.", "type": "string", "format": "uuid", "required": true }, { "in": "path", "name": "dataflowId", "description": "The dataflow ID.", "type": "string", "format": "uuid", "required": true } ], "responses": { "202": { "description": "Request accepted, job execution is in progress.\n\n---\n**Headers:**\n\n**Location** `string` - The URL to the job instance resource.\n\n**Retry-After** `integer` - The number of seconds the client should wait before polling the job status for the first time. Clients must use this value to determine when to check the job status and should wait at least this many seconds before the first status poll." }, "429": { "description": "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.", "x-ms-error-response": true, "headers": { "Retry-After": { "type": "integer", "description": "The number of seconds to wait before retrying the request." } }, "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } }, "default": { "description": "Common error codes:\n\n* InsufficientPrivileges - The caller does not have sufficient permissions to run job instance.\n\n* InvalidJobType - The requested job type is invalid.\n\n* TooManyRequestsForJobs - The caller requests too many on-demand job requests.\n\n* ItemNotFound - Requested item ID not found.", "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } } }, "x-ms-examples": { "Run dataflow ApplyChanges job instance example": { "$ref": "./examples/RunOnDemandDataflowApplyChangesJob.json" } } } }, "/workspaces/{workspaceId}/dataflows/{dataflowId}/executeQuery": { "post": { "summary": "Executes a query against a dataflow and returns the result.", "description": "Executes a specified query against a dataflow and streams the result back to the caller. Supports using custom mashup documents for advanced scenarios.\n\nThis API supports [long running operations (LRO)](/rest/api/fabric/articles/long-running-operation).\n\n## Permissions\n\nThe caller must have *execute* permissions for the dataflow.\n\n## Required Delegated Scopes\n\nDataflow.Execute.All or Item.Execute.All.\n\n## Limitations\n\nQueries can run for a maximum of 90 seconds.\n\n## Microsoft Entra supported identities\n\nThis API supports the Microsoft [identities](/rest/api/fabric/articles/identity-support) listed in this section.\n\n| Identity | Support |\n|-|-|\n| User | Yes |\n| [Service principal](/entra/identity-platform/app-objects-and-service-principals#service-principal-object) and [Managed identities](/entra/identity/managed-identities-azure-resources/overview) | Yes |\n\n## Response formats\n\nUse the `Accept` header to negotiate the response media type. Today, the [Apache Arrow](https://arrow.apache.org/) streaming format is the only available response format; additional formats may be offered in the future.\n\n### Apache Arrow streaming format\n\n**Media type:** `application/vnd.apache.arrow.stream`\n\nWhen sending this media type, the `pq-arrow-version` media-type parameter is **required** and selects the Arrow encoding version:\n\n- `pq-arrow-version=1` — Original Apache Arrow encoding. Compatible with all dataflows, including those that connect through an on-premises data gateway.\n- `pq-arrow-version=2` — Newer Apache Arrow encoding with improved streaming performance. Not supported for dataflows that connect through an on-premises data gateway.\n\nExample: `Accept: application/vnd.apache.arrow.stream;pq-arrow-version=2`\n\nIf the `Accept` header is omitted entirely (or `*/*` is sent), the response defaults to `application/vnd.apache.arrow.stream;pq-arrow-version=1`.\n\n## Interface", "tags": [ "QueryExecution" ], "operationId": "QueryExecution_ExecuteQuery", "consumes": [ "application/json" ], "produces": [ "application/json" ], "x-ms-fabric-sdk-long-running-operation": true, "parameters": [ { "in": "path", "name": "workspaceId", "description": "The workspace ID.", "type": "string", "format": "uuid", "required": true }, { "in": "path", "name": "dataflowId", "description": "The Dataflow ID.", "type": "string", "format": "uuid", "required": true }, { "in": "header", "name": "Accept", "description": "The desired media type of the response. See the operation description for the list of supported response formats. Today, only `application/vnd.apache.arrow.stream` is supported; when sending this media type, the `pq-arrow-version` parameter is required and must be either `1` or `2` (e.g. `application/vnd.apache.arrow.stream;pq-arrow-version=1`). If the header is omitted entirely, the default `application/vnd.apache.arrow.stream;pq-arrow-version=1` is used.", "required": false, "type": "string" }, { "in": "body", "name": "executeQueryRequest", "description": "Execute query request payload.", "schema": { "$ref": "./definitions.json#/definitions/ExecuteQueryRequest" }, "required": true } ], "responses": { "200": { "description": "Query result was successfully streamed. The response body is encoded in the media type negotiated via the request's `Accept` header (see the operation description for the list of supported response formats).\n\nWhen the response is in the Apache Arrow streaming format (`application/vnd.apache.arrow.stream`, the only format available today), results are streamed as Apache Arrow IPC; the Arrow encoding version returned matches the `pq-arrow-version` parameter sent on the request's `Accept` header (default `1`). Refer to the [Arrow documentation](https://arrow.apache.org/docs/python/ipc.html#reading-from-stream-and-file-format-for-pandas) on how to read the stream in Python and other languages. Errors encountered during query execution or streaming are reported in an additional column at the end named 'PQ Arrow Metadata'.", "schema": { "type": "file" } }, "202": { "description": "Request accepted, query execution in progress.", "headers": { "Location": { "description": "The URL of the operation status, which can be used to track the operation state.", "type": "string" }, "x-ms-operation-id": { "description": "The operation ID which can be used with long running operations (LRO) APIs to track the operation state and get the result.", "type": "string", "format": "uuid" }, "Retry-After": { "type": "integer", "description": "The number of seconds to wait before retrying the request." } } }, "429": { "description": "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.", "x-ms-error-response": true, "headers": { "Retry-After": { "type": "integer", "description": "The number of seconds to wait before retrying the request." } }, "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } }, "default": { "description": "Common error codes:\n\n* DataflowExecuteQueryError - Query execution failed. Some possible reasons include: the specified query name is invalid or empty, the custom mashup document is invalid, or the specified query name was not found in the dataflow (or in the custom mashup document if provided).", "schema": { "$ref": "../common/definitions.json#/definitions/ErrorResponse" } } } } } }, "responses": {}, "security": [], "tags": [] }