Manage and refresh materialized lake views in Fabric with APIs

Microsoft Fabric REST APIs enable you to manage and refresh Materialized Lake Views (MLVs) programmatically. You can automate lineage refresh operations and integrate them with other tools and systems.

Prerequisites

Before you use the materialized lake views REST APIs, complete these prerequisites:

Register an application with Microsoft Entra ID with appropriate identity. Acquire an access token with appropriate scopes and pass it in the Authorization header of every request.
Replace the placeholders including {WORKSPACE_ID} and {LAKEHOUSE_ID} with appropriate WorkspaceId and LakehouseId. To find these IDs, open the lakehouse in the Fabric portal — the URL contains both: https://app.fabric.microsoft.com/groups/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}. Alternatively, you can list the workspaces and lakehouses using Fabric REST APIs to access them programmatically.

The following job scheduler actions are available for materialized lake views.

Action	Description
Create Refresh Schedule for MLV	Create a schedule for periodic refresh of MLVs.
Get Schedule for MLV	Get details of an existing refresh schedule.
List Schedules for MLV	List all refresh schedules.
Update Refresh Schedule for MLV	Update an existing refresh schedule.
Delete Refresh Schedule for MLV	Delete a refresh schedule.
Run On Demand Refresh for MLVs	Run an immediate refresh of MLVs.
List Job Instances for MLV	List all refresh job instances.
Get Job Instance Details for MLV	Get details of a specific refresh job, such as status.
Cancel Job Instance for MLV	Cancel an in-progress refresh job.

For more information, see job scheduler, where {item} is Lakehouse and {jobType} is RefreshMaterializedLakeViews.

An MLV execution definition is a saved configuration that specifies which materialized lake views to refresh, which upstream lakehouses to include, and which refresh mode and Spark environment to use. It defines a subset of the lineage that can be refreshed independently.

The following actions are available for MLV execution definitions.

Action	Description
Create MLV Execution Definition	Create a new MLV execution definition.
List MLV Execution Definitions	List all MLV execution definitions.
Get MLV Execution Definition	Get details of an existing MLV execution definition.
Update MLV Execution Definition	Update an existing MLV execution definition.
Delete MLV Execution Definition	Delete an MLV execution definition.

For more information, see materialized lake views.

The following diagrams show how to refresh materialized lake views, with or without an MLV execution definition.

Use case 1: Refresh all MLVs in a lakehouse (default)

Use case 2: Refresh specific MLVs or a subset of the lineage

Note

These scenarios cover usage examples specific to materialized lake views. Examples for common Fabric item APIs aren't included.

Examples of refreshing materialized lake views using APIs

Each example shows the HTTP method, endpoint URL, and sample request/response payloads.

Create Refresh Schedule for MLV

Create a schedule for periodic lineage refresh. To refresh only a subset of the lineage, provide the 'mlvExecutionDefinitionId' in executionData. For more information, see Create Refresh Materialized Lake Views Schedule and Get MLV Execution Definition.

Sample request without MLV Execution Definition:

POST https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/RefreshMaterializedLakeViews/schedules

{
  "enabled": true,
  "configuration": {
    "startDateTime": "YYYY-MM-DDTHH:mm:ss",
    "endDateTime": "YYYY-MM-DDTHH:mm:ss",
    "localTimeZoneId": "Central Standard Time",
    "type": "Cron",
    "interval": 10
  }
}

Sample request with MLV Execution Definition:

POST https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/RefreshMaterializedLakeViews/schedules

{
  "enabled": true,
  "configuration": {
    "startDateTime": "YYYY-MM-DDTHH:mm:ss",
    "endDateTime": "YYYY-MM-DDTHH:mm:ss",
    "localTimeZoneId": "Central Standard Time",
    "type": "Cron",
    "interval": 10
  },
  "executionData": {
    "mlvExecutionDefinitionId": "<mlvExecutionDefinitionId>"
  }
}

Sample response:

Status code: 201 Created

Location: https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/RefreshMaterializedLakeViews/schedules/<scheduleId>

{
  "id": "<scheduleId>",
  "enabled": true,
  "createdDateTime": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
  "configuration": {
    "startDateTime": "YYYY-MM-DDTHH:mm:ss",
    "endDateTime": "YYYY-MM-DDTHH:mm:ss",
    "localTimeZoneId": "Central Standard Time",
    "type": "Cron",
    "interval": 10
  },
  "owner": {
    "id": "<ownerId>",
    "type": "User"
  }
}

Get Schedule for MLV

Get details of an existing refresh schedule. For more information, see get item schedules with {item} as Lakehouse and {jobType} as RefreshMaterializedLakeViews.

Sample request:

GET https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/RefreshMaterializedLakeViews/schedules/{scheduleId}

Sample response:

Status code: 200 OK

{
  "id": "<scheduleId>",
  "enabled": true,
  "createdDateTime": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
  "configuration": {
    "startDateTime": "YYYY-MM-DDTHH:mm:ss",
    "endDateTime": "YYYY-MM-DDTHH:mm:ss",
    "localTimeZoneId": "Central Standard Time",
    "type": "Cron",
    "interval": 10
  },
  "executionData": {
    "mlvExecutionDefinitionId": "<mlvExecutionDefinitionId>"
  },
  "owner": {
    "id": "<ownerId>",
    "type": "User"
  }
}

List Schedules for MLV

List all refresh schedules. For more information, see List Item Schedules with {item} as Lakehouse and {jobType} as RefreshMaterializedLakeViews.

Sample request:

GET https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/RefreshMaterializedLakeViews/schedules

Sample response:

Status code: 200 OK

{
  "value": [
    {
      "id": "<scheduleId_1>",
      "enabled": true,
      "createdDateTime": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
      "configuration": {
        "startDateTime": "YYYY-MM-DDTHH:mm:ss",
        "endDateTime": "YYYY-MM-DDTHH:mm:ss",
        "localTimeZoneId": "Central Standard Time",
        "type": "Weekly",
        "weekdays": [
          "Monday",
          "Tuesday"
        ],
        "times": [
          "HH:mm",
          "HH:mm"
        ]
      },
      "owner": {
        "id": "<ownerId>",
        "type": "User"
      }
    },
    {
      "id": "<scheduleId_2>",
      "enabled": true,
      "createdDateTime": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
      "configuration": {
        "startDateTime": "YYYY-MM-DDTHH:mm:ss",
        "endDateTime": "YYYY-MM-DDTHH:mm:ss",
        "localTimeZoneId": "Central Standard Time",
        "type": "Daily",
        "times": [
          "HH:mm",
          "HH:mm"
        ]
      },
      "owner": {
        "id": "<ownerId>",
        "type": "User"
      }
    }
  ]
}

Update Refresh Schedule for MLV

Update an existing refresh schedule. For more information, see Update Refresh Materialized Lake Views Schedule.

Sample request:

PATCH https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/RefreshMaterializedLakeViews/schedules/{scheduleId}

{
  "enabled": true,
  "configuration": {
    "startDateTime": "YYYY-MM-DDTHH:mm:ss",
    "endDateTime": "YYYY-MM-DDTHH:mm:ss",
    "localTimeZoneId": "Central Standard Time",
    "type": "Cron",
    "interval": 10
  },
  "executionData": {
    "mlvExecutionDefinitionId": "<mlvExecutionDefinitionId>"
  }
}

Sample response:

Status code: 200 OK

{
  "id": "<scheduleId>",
  "enabled": true,
  "createdDateTime": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
  "configuration": {
    "startDateTime": "YYYY-MM-DDTHH:mm:ss",
    "endDateTime": "YYYY-MM-DDTHH:mm:ss",
    "localTimeZoneId": "Central Standard Time",
    "type": "Cron",
    "interval": 10
  },
  "executionData": {
    "mlvExecutionDefinitionId": "<mlvExecutionDefinitionId>"
  },
  "owner": {
    "id": "<ownerId>",
    "type": "User"
  }
}

Delete Refresh Schedule for MLV

Delete a refresh schedule. For more information, see Delete Refresh Materialized Lake Views Schedule.

Sample request:

DELETE https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/RefreshMaterializedLakeViews/schedules/{scheduleId}

Sample response:

Status code: 200 OK

Run On Demand Refresh for MLVs

Run an immediate refresh of lineage. To refresh only a subset of the lineage, provide the 'mlvExecutionDefinitionId' in executionData. For more information, see Run On Demand Refresh Materialized Lake Views and Get MLV Execution Definition.

Sample request without MLV Execution Definition:

POST https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/RefreshMaterializedLakeViews/instances

Sample request with MLV Execution Definition:

POST https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/RefreshMaterializedLakeViews/instances

{
  "executionData": {
    "mlvExecutionDefinitionId": "<mlvExecutionDefinitionId>"
  }
}

Sample response:

Status code: 202 Accepted

Location: https://api.fabric.microsoft.com/v1/workspaces/<WORKSPACE_ID>/lakehouses/<LAKEHOUSE_ID>/jobs/instances/<jobInstanceId>
Retry-After: 60

With the Location header, you can use Get Item Job Instance to check job status or Cancel Item Job Instance to cancel the run.

List Job Instances for MLV

List all refresh job instances. For more information, see List Item Job Instances with {item} as Lakehouse and {jobType} RefreshMaterializedLakeViews. The job status reflects the status in Monitor hub.

Sample request:

GET https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/RefreshMaterializedLakeViews/instances

Sample response:

Status code: 200 OK

{
  "value": [
    {
      "id": "<jobInstanceId_1>",
      "itemId": "<LAKEHOUSE_ID>",
      "jobType": "RefreshMaterializedLakeViews",
      "invokeType": "Manual",
      "status": "<status>",
      "rootActivityId": "<rootActivityId_1>",
      "startTimeUtc": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
      "endTimeUtc": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
      "failureReason": null
    },
    {
      "id": "<jobInstanceId_2>",
      "itemId": "<LAKEHOUSE_ID>",
      "jobType": "RefreshMaterializedLakeViews",
      "invokeType": "Scheduled",
      "status": "<status>",
      "rootActivityId": "rootActivityId_2",
      "startTimeUtc": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
      "endTimeUtc": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
      "failureReason": null
    }
  ]
}

Get Job Instance Details for MLV

Get status and details for a specific refresh job instance. For more information, see Get Item Job Instance with {item} as Lakehouse. The job status reflects the status in Monitor hub.

Sample request:

GET https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/instances/{jobInstanceId}

Sample response:

Status code: 200 OK

{
  "id": "<id>",
  "itemId": "<itemId>",
  "jobType": "RefreshMaterializedLakeViews",
  "invokeType": "<invokeType>",
  "status": "<status>",
  "rootActivityId": "<rootActivityId>",
  "startTimeUtc": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
  "endTimeUtc": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
  "failureReason": null
}

Cancel Job Instance for MLV

Cancel an in-progress refresh job. For more information, see Cancel Item Job Instance with {item} as Lakehouse.

Sample request:

POST https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/jobs/instances/{jobInstanceId}/cancel

Sample response:

Status code: 202 Accepted

Location: https://api.fabric.microsoft.com/v1/workspaces/<WORKSPACE_ID>/lakehouses/<LAKEHOUSE_ID>/jobs/instances/<jobInstanceId>
Retry-After: 60

Examples of using MLV execution definition APIs

Each example shows the HTTP method, endpoint URL, and sample request/response payloads.

Create MLV Execution Definition

Create a new MLV execution definition that specifies which MLVs and upstream lakehouses to include, along with the refresh mode and Spark environment. For more information, see Create Mlv Execution Definition.

Sample request:

POST https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/mlvexecutiondefinitions

{
  "displayName": "Gold Chain – Sales",
  "description": "Nightly refresh for the Sales gold-layer views",
  "settings": {
    "environment": {
      "referenceType": "ById",
      "itemId": "<ENVIRONMENT_ID>",
      "workspaceId": "<ENVIRONMENT_WORKSPACE_ID>"
    },
    "refreshMode": "Optimal"
  },
  "currentLakehouseExecutionContext": {
    "mode": "Selected",
    "selectedMlvs": [
      "dbo.gold_sales_summary",
      "dbo.gold_sales_daily"
    ]
  },
  "extendedLineageExecutionContext": {
    "mode": "All"
  }
}

Sample response:

Status code: 201 Created

Location: https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/mlvexecutiondefinitions/<mlvExecutionDefinitionId>

{
  "id": "<mlvExecutionDefinitionId>",
  "displayName": "Gold Chain – Sales",
  "description": "Nightly refresh for the Sales gold-layer views",
  "settings": {
    "environment": {
      "referenceType": "ById",
      "itemId": "<ENVIRONMENT_ID>",
      "workspaceId": "<ENVIRONMENT_WORKSPACE_ID>"
    },
    "refreshMode": "Optimal"
  },
  "currentLakehouseExecutionContext": {
    "mode": "Selected",
    "selectedMlvs": [
      "dbo.gold_sales_summary",
      "dbo.gold_sales_daily"
    ]
  },
  "extendedLineageExecutionContext": {
    "mode": "All"
  }
}

List MLV Execution Definitions

List all MLV execution definitions. For more information, see List Mlv Execution Definitions.

Sample request:

GET https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/mlvexecutiondefinitions

Sample response:

Status code: 200 OK

{
  "value": [
    {
      "id": "<mlvExecutionDefinitionId_1>",
      "displayName": "Gold Chain – Sales",
      "description": "Nightly refresh for the Sales gold-layer views",
      "settings": {
        "environment": {
          "referenceType": "ById",
          "itemId": "<ENVIRONMENT_ID>",
          "workspaceId": "<ENVIRONMENT_WORKSPACE_ID>"
        },
        "refreshMode": "Optimal"
      },
      "currentLakehouseExecutionContext": {
        "mode": "Selected",
        "selectedMlvs": [
          "dbo.gold_sales_summary",
          "dbo.gold_sales_daily"
        ]
      },
      "extendedLineageExecutionContext": {
        "mode": "All"
      }
    },
    {
      "id": "<mlvExecutionDefinitionId_2>",
      "displayName": "Silver Chain – Customers",
      "currentLakehouseExecutionContext": {
        "mode": "All"
      }
    }
  ]
}

Get MLV Execution Definition

Get details of an existing MLV execution definition, including the MLVs to refresh, upstream lakehouses to include, refresh mode, and Spark environment. For more information, see Get Mlv Execution Definition.

Sample request:

GET https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/mlvexecutiondefinitions/{mlvExecutionDefinitionId}

Sample response:

Status code: 200 OK

{
  "id": "<mlvExecutionDefinitionId>",
  "displayName": "Gold Chain – Sales",
  "description": "Nightly refresh for the Sales gold-layer views",
  "settings": {
    "environment": {
      "referenceType": "ById",
      "itemId": "<ENVIRONMENT_ID>",
      "workspaceId": "<ENVIRONMENT_WORKSPACE_ID>"
    },
    "refreshMode": "Optimal"
  },
  "currentLakehouseExecutionContext": {
    "mode": "Selected",
    "selectedMlvs": [
      "dbo.gold_sales_summary",
      "dbo.gold_sales_daily"
    ]
  },
  "extendedLineageExecutionContext": {
    "mode": "All"
  }
}

Update MLV Execution Definition

Update an existing MLV execution definition. Only the fields provided in the request body are updated; omitted fields retain their existing values. For more information, see Update Mlv Execution Definition.

Sample request:

PATCH https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/mlvexecutiondefinitions/{mlvExecutionDefinitionId}

{
  "displayName": "Updated Gold Chain – Sales",
  "settings": {
    "refreshMode": "Full"
  },
  "currentLakehouseExecutionContext": {
    "mode": "All"
  },
  "extendedLineageExecutionContext": {
    "mode": "Selected",
    "selectedLakehouses": [
      {
        "referenceType": "ById",
        "itemId": "<UPSTREAM_LAKEHOUSE_ID>",
        "workspaceId": "<UPSTREAM_WORKSPACE_ID>"
      }
    ]
  }
}

Sample response:

Status code: 200 OK

{
  "id": "<mlvExecutionDefinitionId>",
  "displayName": "Updated Gold Chain – Sales",
  "description": "Nightly refresh for the Sales gold-layer views",
  "settings": {
    "environment": {
      "referenceType": "ById",
      "itemId": "<ENVIRONMENT_ID>",
      "workspaceId": "<ENVIRONMENT_WORKSPACE_ID>"
    },
    "refreshMode": "Full"
  },
  "currentLakehouseExecutionContext": {
    "mode": "All"
  },
  "extendedLineageExecutionContext": {
    "mode": "Selected",
    "selectedLakehouses": [
      {
        "referenceType": "ById",
        "itemId": "<UPSTREAM_LAKEHOUSE_ID>",
        "workspaceId": "<UPSTREAM_WORKSPACE_ID>"
      }
    ]
  }
}

Delete MLV Execution Definition

Delete an MLV execution definition. Any schedules linked to it are also removed. For more information, see Delete Mlv Execution Definition.

Sample request:

DELETE https://api.fabric.microsoft.com/v1/workspaces/{WORKSPACE_ID}/lakehouses/{LAKEHOUSE_ID}/mlvexecutiondefinitions/{mlvExecutionDefinitionId}

Sample response:

Status code: 200 OK

Known limitations

The following limitations apply to the materialized lake views REST APIs:

Limits of Job Scheduler APIs:
- The job scheduler enforces limits on how many schedules can be configured per lakehouse.
- The job scheduler API returns a limited number of completed and active jobs, which can affect visibility into historical or concurrent executions.
- The throttling limits for Fabric public APIs apply to materialized lake views APIs.
Job status display: The status returned by list item job instances and get item job instance reflects status in Monitor hub. It might differ from materialized lake views run history status (for example, Skipped appears as Canceled in Monitor hub).
Refresh limits: For refresh constraints, see permissions and limitations.

Feedback

Was this page helpful?

Last updated on 2026-07-01

Manage and refresh materialized lake views in Fabric with APIs

Prerequisites

Examples of refreshing materialized lake views using APIs

Create Refresh Schedule for MLV

Get Schedule for MLV

List Schedules for MLV

Update Refresh Schedule for MLV

Delete Refresh Schedule for MLV

Run On Demand Refresh for MLVs

List Job Instances for MLV

Get Job Instance Details for MLV

Cancel Job Instance for MLV

Examples of using MLV execution definition APIs

Create MLV Execution Definition

List MLV Execution Definitions

Get MLV Execution Definition

Update MLV Execution Definition

Delete MLV Execution Definition

Known limitations

Related content

Feedback

Additional resources