Skip to main content

DBT Cloud Client and Helper Functions

API Client

The DBT Cloud Client is a Python class designed to interact with the dbt Cloud API (version 2). It provides methods to perform various operations on dbt Cloud, such as triggering job runs and retrieving job run status.

from dlt.helpers.dbt_cloud import DBTCloudClientV2

# Initialize the client
client = DBTCloudClientV2(api_token="YOUR_API_TOKEN", account_id="YOUR_ACCOUNT_ID")

# Example: Trigger a job run
job_run_id = client.trigger_job_run(job_id=1234, data={"cause": "Triggered via API"})
print(f"Job run triggered successfully. Run ID: {job_run_id}")

# Example: Get run status
run_status = client.get_run_status(run_id=job_run_id)
print(f"Job run status: {run_status['status_humanized']}")

Helper functions

These Python functions provide an interface to interact with the dbt Cloud API. They simplify the process of triggering and monitoring job runs in dbt Cloud.


This function triggers a job run in dbt Cloud using the specified configuration. It supports various customization options and allows for monitoring the job's status.

from dlt.helpers.dbt_cloud import run_dbt_cloud_job

# Trigger a job run with default configuration
status = run_dbt_cloud_job()

# Trigger a job run with additional data
additional_data = {
"git_sha": "abcd1234",
"schema_override": "custom_schema",
# ... other parameters
status = run_dbt_cloud_job(job_id=1234, data=additional_data, wait_for_outcome=True)


If you have already started job run and have a run ID, then you can use the get_dbt_cloud_run_status function.

This function retrieves the full information about a specific dbt Cloud job run. It also supports options for waiting until the run is complete.

from dlt.helpers.dbt_cloud import get_dbt_cloud_run_status

# Retrieve status for a specific run
status = get_dbt_cloud_run_status(run_id=1234, wait_for_outcome=True)

Set credentials


When using a dlt locally, we recommend using the .dlt/secrets.toml method to set credentials.

If you used the dlt init command, then the .dlt folder has already been created. Otherwise, create a .dlt folder in your working directory and a secrets.toml file inside it.

It's where you store sensitive information securely, like access tokens. Keep this file safe.

Use the following format for dbt Cloud API authentication:

api_token = "set me up!" # required for authentication
account_id = "set me up!" # required for both helpers function
job_id = "set me up!" # optional only for run_dbt_cloud_job function (you can pass this explicitly as an argument to the function)
run_id = "set me up!" # optional for get_dbt_cloud_run_status (you can pass this explicitly as an argument to the function)

Environment variables

dlt supports reading credentials from environment.

If dlt tries to read this from environment variables, it will use a different naming convention.

For environment variables all names are capitalized and sections are separated with double underscore "__".

For example, for the above secrets, we would need to put into environment:


For more information, read the Credentials documentation.

This demo works on codespaces. Codespaces is a development environment available for free to anyone with a Github account. You'll be asked to fork the demo repository and from there the README guides you with further steps.
The demo uses the Continue VSCode extension.

Off to codespaces!


Ask a question

Welcome to "Codex Central", your next-gen help center, driven by OpenAI's GPT-4 model. It's more than just a forum or a FAQ hub – it's a dynamic knowledge base where coders can find AI-assisted solutions to their pressing problems. With GPT-4's powerful comprehension and predictive abilities, Codex Central provides instantaneous issue resolution, insightful debugging, and personalized guidance. Get your code running smoothly with the unparalleled support at Codex Central - coding help reimagined with AI prowess.