Lineage-aware AI with the Fabric item relations API (Preview)

With two new REST operations, you can retrieve the upstream and downstream relations of any Fabric item directly from your own code — the dependency graph behind the portal's lineage view, now available as a supported, programmable surface. Each response includes related items, the typed relation edges that connect them, and the workspaces those items belong to. 

Lineage has always answered two human questions: “where does this data come from?” and “what breaks if I change it?” This API lets your tools — and your AI agents — ask those same questions programmatically. 

What’s new 

Until now, item lineage in Fabric was something you explored visually in the portal. You opened an item, looked at its lineage view, and traced dependencies by eye. That’s great for people, but it’s difficult to automate. 

With this update, lineage becomes an API. After authenticating to Fabric, you can programmatically: 

• Get the downstream relations of an item — everything that depends on it (its consumers and impact radius). 
• Get the upstream relations of an item — everything it depends on (its sources). 
• Read the typed relation edges between items (for example, Shortcut, PushData, Orchestration). 
• Resolve related items across workspaces, using the workspace list returned alongside the graph. 
• Feed lineage into impact analysis, documentation, data catalogs, CI/CD checks, and AI agents. 

Why this matters 

If you only work in the Fabric portal, the lineage view already serves you well. The impact of this update shows up once you need to automate or scale — when understanding dependencies becomes part of a workflow rather than a manual click-through. A few examples: 

• Before you delete or reroute a dataset, you call the downstream API to see every report, semantic model, and pipeline that would be affected. 
• You build an internal catalog or documentation site that shows each item’s sources and consumers, kept fresh automatically. 
• You add a CI/CD check that fails a deployment if a change would break a downstream dependency. 
• You are an ISV building on Fabric, and you want lineage to be part of your product experience — not a side trip into the portal. 

That’s what a public API is for: turning a visual experience into a building block you can automate and compose. 

Lineage is context for AI 

AI agents are only as good as the context they are given. When an agent answers a question about a table, a report, or a metric, it benefits enormously from knowing where that data came from and what depends on it. Lineage is exactly that context. 

With the relations API, an agent can traverse an item’s dependency graph as part of its reasoning. Ask “is it safe to change this table?” and the agent can call the downstream API, enumerate the affected items, and ground its answer in the real graph instead of guessing. Ask “where does this number come from?” and it can walk upstream to the source. In other words, lineage helps ground AI responses in the actual dependency graph rather than inferred relationships. 

This is the same pattern we see across Fabric’s AI story: take governance metadata your organization already maintains — like sensitivity labels — and share it with AI so agents understand your data the way your organization does. Lineage joins that toolkit. It gives agents dependency awareness: the ability to reason about cause, effect, and blast radius, not just content. 

How it works 

At a high level, the API exposes both sides of the dependency graph: what an item depends on and what depends on it. The API adds two GET operations under the platform surface. Because the API is in preview, every call currently requires beta=true as a query parameter. 

GET /v1/workspaces/{workspaceId}/items/{itemId}/relations/downstream?beta=true 

GET /v1/workspaces/{workspaceId}/items/{itemId}/relations/upstream?beta=true 

The caller needs read permission on the item. Both user and service principal identities are supported. 

Each response is a small graph made of three lists: 

• items — every item in the returned graph, including the item you queried, so each relation endpoint can be resolved (id, type, display name, and the workspace they belong to). 

• relations — the edges, each with a source item, the item it depends on, and a relation type. 

• workspaces — the workspaces referenced by those items, so you can resolve names across workspace boundaries. 

A downstream response for a semantic model consumed by a report looks like this: 

{ 

  "items": [ 

    { "id": "3546052c-...", "type": "Report", 

      "displayName": "Q4 Sales Dashboard", "workspaceId": "cfafbeb1-..." }, 

    { "id": "9b218778-...", "type": "SemanticModel", 

      "displayName": "Sales Semantic Model", "workspaceId": "cfafbeb1-..." } 

  ], 

  "relations": [ 

    { "itemId": "3546052c-...", 

      "dependentOnItemId": "9b218778-...", 

      "relationType": "Association" } 

  ], 

  "workspaces": [ 

    { "id": "cfafbeb1-...", "displayName": "Finance Analytics Workspace" } 

  ] 

} 

The relation types describe how two items are connected. The set is extensible, so new types can be added over time: 

Getting started 

A great first step is to pick a familiar item and explore its downstream relations to understand its impact radius. The following is the shape of a first call using the Azure CLI for authentication: 

1. Authenticate to Fabric and get a token. 

$token = az account get-access-token ` 

  --resource "https://api.fabric.microsoft.com" ` 

  --query accessToken -o tsv 

2. Call the downstream relations API for an item. 

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId} 

      /items/{itemId}/relations/downstream?beta=true 

Authorization: Bearer $token 

3. Read the relations array to list what depends on the item, then walk upstream from any related item to trace it back to its sources. 

From there, wire the results into whatever needs dependency awareness — an impact-analysis check, a catalog page, or an AI agent’s context. You can find the operations in the Fabric REST API reference under the platform items surface:

• Items - Get Downstream Relations (beta) - REST API (Core) | Microsoft Learn
• Items - Get Upstream Relations (beta) - REST API (Core) | Microsoft Learn

Exposing item lineage as a programmable API is a foundational step. It turns the dependency graph into something your tools, pipelines, and agents can read and reason over. We look forward to seeing what you build with it. 

Note: This API is in preview and provided for evaluation and development purposes. It may change based on feedback and is not recommended for production use.