How to Retrieve DBT Model Lineage Using the API

What will you learn?

In this tutorial, you will learn how to extract model lineage information from dbt (Data Build Tool) using its API. Understanding the lineage of your models is crucial for debugging, documentation, and optimizing your data transformation workflows.

Introduction to Problem and Solution

When working on data transformation projects using dbt, it’s essential to comprehend the relationships between different tables or models within your project. This understanding helps in tracking dependencies, predicting the impact of changes, and simplifying debugging processes. By leveraging the dbt API along with other methods available in dbt Cloud or dbt Core environments, you can access and visualize the lineage of your dbt models effectively.


To retrieve model lineage from a dbt project using an API approach:

import requests
import json

# Replace 'your_dbt_cloud_api_token', 'account_id', 'project_id' with your actual values
headers = {
    "Authorization": "Token your_dbt_cloud_api_token",
    "Content-Type": "application/json"

response = requests.get(

metadata = response.json()

for node in metadata['data']['nodes'].values():
    if node['resource_type'] == 'model':
        print(f"Model Name: {node['name']}")
        print("Downstream Dependencies:")
        for downstream_node in node['depends_on']['nodes']:

# Copyright PHD


This Python script uses the requests library to interact with the dbt Cloud API. Here’s a breakdown: – The script sends a GET request to fetch metadata about all nodes (models, seeds, tests, etc.) within a specified project. – It filters through these nodes to specifically identify models. – For each model found, it prints out its name along with names of any downstream dependencies.

This method provides a systematic way to analyze and visualize the connections between different components of your data pipeline.

    1. Can I use this method with both dbt Core and dbt Cloud?

      • Yes! While this example uses an API from dbt Cloud, similar concepts apply when working with artifacts generated by dbt docs generate locally in dbti Core environments.
    2. How do I install the requests library?

      • You can install requests by running pip install requests in your terminal or command prompt.
    3. What permissions are required on my DBT cloud account?

      • You need an account level that allows API access; typically available in paid plans rather than free-tier access.
    4. Can I get real-time updates using this script?

      • The script fetches current state at execution time; re-running it would provide updated insights based on the latest state within targeted project environment(s).
    5. Is there a rate limit on calling DBT’s APIs?

    6. How do I find my Account ID & Project ID?

      • These identifiers are available via URL when navigating through DbT cloud interface as well as within settings/documentation sections relating accounts/projects respectively.

By understanding how to retrieve model lineage through api calls in dbt projects, you gain detailed insights into your Data Build Tool projects’ architecture and design decisions over time. This knowledge empowers teams to make informed decisions regarding optimization efforts, leading to enhanced efficiency across development lifecycles.

Leave a Comment