Manage and refresh materialized lake views in Fabric with APIs

Microsoft Fabric REST APIs provide service endpoints to manage Fabric items. This article describes the public REST APIs available for materialized lake views and how to use them.

With materialized lake view APIs, data engineers and citizen developers can automate lineage operations and integrate them with other tools and systems.

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

For more information, see job scheduler with {jobType} as 'RefreshMaterializedLakeViews'.

Prerequisites

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

• To use Fabric REST APIs, register an application with Microsoft Entra ID and get a Microsoft Entra token for Fabric. Use that token in the authorization header.
• Fabric REST APIs for MLV support Microsoft Entra users. Choose authorization method and scope based on how your app accesses the APIs.
• Fabric REST API uses a unified endpoint model for lineage operations. Replace placeholders such as {WORKSPACE_ID}, {LAKEHOUSE_ID}, and payload values in the examples before calling the APIs.

Examples of REST API usage with materialized lake views

Use the following Fabric REST APIs to schedule, run, retrieve, and manage refresh jobs and schedules for materialized lake views lineage in a lakehouse. Each example shows the HTTP method, endpoint URL, and sample request/response payloads.

Create Schedule for MLV in Lakehouse

Create a new schedule to periodically refresh materialized lake views lineage in a lakehouse. For more information, see job scheduler. Currently, materialized lake views support only one active refresh schedule per lineage. Use Update Schedule to update an existing schedule.

Sample request:

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

Get details of an existing materialized lake views lineage refresh schedule in a lakehouse. For more information, see job scheduler.

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
  },
  "owner": {
    "id": "<ownerId>",
    "type": "User"
  }
}

List Schedules for MLV in Lakehouse

List all refresh schedules created for materialized lake views lineage in a lakehouse. For more information, see job scheduler.

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 Schedule for MLV in Lakehouse

Update an existing refresh schedule for materialized lake views lineage in a lakehouse. For more information, see job scheduler. Currently, materialized lake views support only one active schedule per lineage.

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

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
  },
  "owner": {
    "id": "<ownerId>",
    "type": "User"
  }
}

Delete Schedule for MLV in Lakehouse

Delete an existing refresh schedule for materialized lake views lineage in a lakehouse. For more information, see job scheduler.

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 Job for MLV in Lakehouse

Trigger an immediate refresh of materialized lake views lineage in a lakehouse using an on-demand job. The Spark job starts executing after a successful request. For more information, see job scheduler.

Sample request:

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

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 location, you can use Get Item Job Instance to view job status or use Cancel Item Job Instance to cancel the current lineage run.

List Job Instances for MLV in Lakehouse

List job instances executed for materialized lake views lineage refresh in a lakehouse. For more information, see job scheduler. The job status returned reflects the status shown in Monitoring 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 in Lakehouse

Get execution details such as status and ID for a specific materialized lake views lineage refresh job instance in a lakehouse. For more information, see job scheduler. The job status returned reflects the status shown in Monitoring 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 in Lakehouse

Cancel an ongoing materialized lake views lineage refresh job in a lakehouse. For more information, see job scheduler.

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/<workspaceId>/lakehouses/<LAKEHOUSE_ID>/jobs/instances/<jobInstanceId>
Retry-After: 60

Known limitations

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

• Service principal authentication: Materialized lake views (MLV) don't support authentication through service principals.
• Schedule limits per lakehouse: The job scheduler enforces limits on how many schedules can be configured per lakehouse.
• Single schedule per lineage: MLV supports only one active refresh schedule per lineage. Creating more than one refresh schedule for a lineage might cause UI instability.
• Job status display: The status returned by list item job instances and get item job instance reflects Monitoring hub status. It might differ from materialized lake views run history status (for example, Skipped can appear as Canceled in Monitoring hub).
• Entity display limits: The job scheduler interface displays a limited number of completed and active jobs, which can affect visibility into historical or concurrent executions.

Related content

• Microsoft Fabric REST API
• Job Scheduler APIs in Fabric