Skip to main content

​
Overview

​
Tool Name

​
Purpose

The dbt_cloud_tools provide programmatic access to DBT Cloud. Use them to list resources, fetch rich context, monitor job runs, and analyze performance so you can integrate DBT Cloud operations into your broader workflows.

​
Functions Available

  1. dbt_cloud_analyze_run: Analyze a specific run for timings, test outcomes, artifacts, and performance signals.
  2. dbt_cloud_context: Retrieve account, project, and environment context including connections and settings.
  3. dbt_cloud_list: List resources such as projects, jobs, runs, environments, and connections with pagination.
  4. dbt_cloud_get: Fetch detailed information for a single resource by type and id.
  5. dbt_cloud_run_job: Start an on-demand job run, optionally with a one-run command override.
  6. dbt_cloud_monitor: Poll job execution for a period and emit real time status updates and alerts.
  7. dbt_cloud_verify_presenter_recovery: Run or refresh independent Prover verification for a recovered presenter demo incident.

​
Connection Requirements

Create a dbt Cloud connection in Config -> Connections under Data Pipelines before using these tools. When tools omit an explicit connection, Genesis resolves the caller’s effective default dbt_cloud connection (My default, then Role default; typically the shared dbt_cloud.shared entry) when listing resources, monitoring runs, or analyzing failures. See Default connection layers. For dbt Cloud’s no-default and incomplete-connection behavior, see dbt Cloud connections. Genesis supports two connection modes under Data Pipelines. The stored auth_type selects which token field and Authorization scheme Genesis uses: Both modes share these locator fields:
Genesis injects bot_id, thread_id, and user_id into every tool in this group automatically. You do not pass user_id manually. The runtime uses the calling user and bot as secret-access principals when decrypting Connections-UI secrets (service token, personal access token, GitHub token, and other secret fields). Resolved credential contexts are scoped to those caller principals, so one user’s or bot’s context is not reused for another caller.
dbt Cloud tools read credentials from the saved dbt Cloud connection (or legacy server configuration). They do not accept per-call API tokens. If secret resolution fails because the acting user lacks owner, admin, or RBAC access to the stored secrets, Genesis surfaces that error instead of falling back to older configuration stores.
The dbt_cloud_context tool can view or patch the active conversation context for troubleshooting. When you patch svc_token or github_token with a secret reference (for example secret_* or env_*), Genesis resolves it for runtime API use using the calling user and bot before making dbt Cloud calls. When it writes new secret values, Genesis assigns ownership to the calling user so later tool calls can resolve the same secrets under RBAC.

​
Key Features

Cloud Resource Discovery

Explore projects, jobs, runs, environments, and connections across DBT Cloud accounts.

Run Analytics

Break down model timings, test results, and performance metrics from completed runs.

Context & Config

Pull project and environment context to power governance and documentation.

Live Monitoring

Track job executions in near real time and trigger alerts on failures.

Scalable Listings

Page through large resource sets with filters for status and size.

​
Input Parameters for Each Function

​
dbt_cloud_analyze_run

When dbt_cloud_analyze_run starts nested incident analysis, its analyzer uses the LLM provider configured for the triggering conversation. This keeps the analysis on the same provider instead of switching to a separate default. No additional dbt Cloud or analyzer configuration is required.

​
dbt_cloud_context

All parameters are optional. Omit every field to read the active context; supply one or more fields to patch it for troubleshooting. Use auth_type='service_token' for account-scoped service tokens (sent with Token authorization) and auth_type='personal_access_token' for user-scoped PATs (sent with Bearer authorization). If dbt Cloud calls fail with HTTP 401, confirm the saved auth_type matches the token kind you configured.

​
Response shape (dbt_cloud_context)

Read-only calls (no optional fields supplied) return success, content, and on failure error. If the saved dbt Cloud connection exists but context cannot be loaded (for example the shared connection’s token cannot be resolved under RBAC), Genesis returns success: false, content: {}, and error with the reason — check success before reading content. When you supply any optional field to patch context (acct_id, access_url, svc_token, auth_type, github_user, github_token, bot_name, or slack_channel), Genesis merges the new values even when the existing context cannot be read first, then returns success: true with content set to the merged context. content never includes decrypted or plaintext credentials. For svc_token and github_token: If a patched secret reference cannot be resolved (missing secret, or the calling user or bot lacks access), Genesis returns success: false and error with the resolution reason instead of falling back to legacy configuration.

​
Persisted presenter investigations

When a conversation is bound to a persisted presenter incident, dbt Cloud reads remain scoped to that incident instead of using caller-supplied discovery filters:
  • dbt_cloud_list returns only the incident’s project, environment, job, or failed run.
  • dbt_cloud_get returns only the incident run and its related resources. Resource IDs and artifact requests that do not belong to the incident are rejected.
  • dbt_cloud_context remains read-only for the bound conversation. Attempts to change its dbt Cloud connection are rejected.
  • dbt_cloud_analyze_run analyzes the persisted incident run and uses its isolated presenter workspace, preventing recovery analysis from switching incidents.

​
dbt_cloud_list

When listing runs with dbt_cloud_list, failed_only is a Boolean that defaults to false: the default includes runs across statuses, while failed_only=true limits results to failed runs. Genesis formats the run filters for dbt Cloud’s List Runs API so the request is accepted. Runs remain listable when dbt Cloud omits related job data, such as for a deleted job; monitor and outlier alerts show the job as unknown in that case.

​
dbt_cloud_get

​
Run artifacts

When dbt_cloud_get fetches an artifact for a run, an unavailable artifact does not always mean that a file is missing. A 404 reports that the artifact was not produced by the run; use dbt_cloud_get(kind='run') to list the artifacts that the run produced. A 401 or 403 reports that the caller is not permitted to read the artifact. For manifest.json, Genesis also reports when the response cannot be parsed as JSON or is not a JSON object. Other HTTP errors remain errors rather than being relabeled as missing artifacts.

​
dbt_cloud_monitor

​
dbt_cloud_run_job

Use dbt_cloud_list(resource_type='jobs') to discover a job ID. The tool returns the new run ID, initial status, and dbt Cloud link; follow it with dbt_cloud_get(resource_type='runs', resource_id=...) or dbt_cloud_analyze_run(run_id=...). For a presenter recovery, Genesis binds the run to the persisted investigation context instead of resolving a potentially different default connection. The incident ID, authenticated user, job ID, and exact dbt Cloud connection must match that context; otherwise Genesis refuses to start the recovery run.

​
dbt_cloud_verify_presenter_recovery

Call this only after the tracked dbt Cloud recovery run succeeds. Genesis compares the isolated presenter fixture’s authoritative owner mapping against the repaired model output using the scenario’s configured Prover comparison key on both sides, plus fully qualified Snowflake database and schema identities from the incident fixture. It then persists the Prover verdict with the original failure, code diff, and recovery run.

​
Response shape (dbt_cloud_verify_presenter_recovery)

When content has no terminal verdict, poll this same tool with the same presenter_incident_id and job_id. If a prior Prover attempt ended with status: "error", calling the tool again starts a fresh verification and preserves the earlier attempt in prior_attempts. When Prover returns FAIL, treat the reported mismatches as new remediation evidence: explain the exact mismatch, propose the smallest correction on the same isolated branch, wait for explicit approval, delegate that correction, rerun the same ordinary dbt job, and start a fresh Prover verification. Repeat only while Prover reports evidence-backed failures; stop on PASS or report the exact infrastructure blocker. Use dbt_cloud_run_job to start the recovery run and dbt_cloud_analyze_run to inspect dbt execution evidence. If the stored presenter incident does not yet recognize a successful recovery, this tool refreshes the attached recovery run from dbt Cloud before retrying verification. The refreshed run must still match the incident’s authenticated user, job, project, and environment; otherwise verification fails. This tool only verifies a successful tracked presenter recovery — it does not replace run analysis or job execution.
For large listings, supply limit and offset to control pagination and avoid hitting rate limits.

​
Use Cases

  1. Production Run Monitoring Track nightly jobs, emit alerts on failure, and post summaries to Slack.
  2. Performance Analysis Identify slow models by timing breakdowns and compare runs week over week.
  3. Ops Dashboards Feed run status and duration metrics into centralized observability tools.
  4. Governance & Docs Pull project and environment context for documentation and audits.
  5. Incident Automation On failure, fetch logs and artifacts, open a ticket, and notify owners.
  6. Presenter demo recovery verification After a trusted dbt Cloud presenter incident is repaired and the recovery run succeeds, verify the fix with dbt_cloud_verify_presenter_recovery and poll until Prover returns PASS before claiming recovery.

​
Workflow/How It Works

  1. Configure a dbt Cloud connection under Config -> Connections (or confirm legacy server configuration is present), then run Test Connection so secrets resolve for your user.
  2. Discover resources using dbt_cloud_list, or get details via dbt_cloud_get.
  3. Monitor active jobs with dbt_cloud_monitor for live status.
  4. Analyze completed executions using dbt_cloud_analyze_run to extract timings, tests, and artifacts.
  5. Act on insights by notifying teams, updating tickets, or storing reports.
  6. Verify presenter demo recovery with dbt_cloud_verify_presenter_recovery after a successful tracked recovery run.

​
Integration Relevance

  • dbt_action to coordinate local and Cloud operations.
  • data_connector_tools to validate downstream warehouse connectivity.
  • project_manager_tools for issue tracking and task automation.
  • slack_tools for status notifications and alerts.
  • file_manager_tools to persist run reports, logs, and artifacts.

​
Configuration Details

  • Prefer the saved dbt Cloud connection in Config -> Connections; use dbt_cloud_context only when troubleshooting or patching context for the current conversation.
  • Ensure the user driving the agent conversation can resolve connection secrets (owner of the saved secrets, admin, or RBAC grant). Other users see access-denied errors even when the connection exists.
  • Validate account_id, project_id, environment_id, job_id, and run_id against DBT Cloud.
  • Choose monitor_duration that reflects expected job times to reduce unnecessary polling.
  • Align alerting with your existing notification channels and on call practices.
Store service tokens, personal access tokens, and GitHub tokens as connection secrets. Rotate them on your normal cadence and never embed tokens in source files or chat logs. A 401 from dbt Cloud often means the connection’s auth_type does not match the token kind — service tokens require service_token; PATs require personal_access_token.
See also Connections for the Data Pipelines setup workflow.

​
Limitations or Notes

  1. Requires an active DBT Cloud subscription and API access.
  2. API rate limits apply and vary by plan.
  3. Monitoring granularity depends on DBT Cloud polling frequency.
  4. Very large result sets require pagination to avoid timeouts.
  5. Historical retention and artifact availability may be limited by account settings.
  6. Cross account resource access needs explicit permissions.
  7. In the Databricks App, run_git_command is unavailable. git_action is also refused for repositories with unsafe local Git configuration or submodules; see Git Action Tools.

​
Output

  • Run Analysis: Model timings, tests, artifacts, and summary metrics. Successful runs also include the run details as JSON in the analysis.
  • Context: Project, environment, and connection configuration.
  • Listings: Paginated arrays of resources with metadata.
  • Details: Full records for specific resources.
  • Monitoring: Status updates, progress signals, and optional failure alerts.
  • Errors: Clear messages for authentication, permission, or connectivity issues.