> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DBT Cloud Tools

> Explore, monitor, and analyze DBT Cloud projects, jobs, runs, and environments through authenticated API calls.

## **Overview**

### **Tool Name**

```json theme={null}
dbt_cloud_tools
```

### **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](/docs/Setup/Connections#default-connection-layers).
For dbt Cloud's no-default and incomplete-connection behavior, see
[dbt Cloud connections](/docs/Setup/Connections#dbt-cloud-connections).

Genesis supports two connection modes under **Data Pipelines**. The stored
`auth_type` selects which token field and Authorization scheme Genesis uses:

| Mode | Stored `auth_type` | Token field | Authorization |
| - | - | - | - |
| **Service Token** | `service_token` | `service_token` | `Token` (account-level; best for shared / production) |
| **Personal Access Token** | `personal_access_token` | `personal_access_token` | `Bearer` (user-scoped PAT; acts on your behalf) |

Both modes share these locator fields:

| Field | Stored key | Type | Required | Notes |
| - | - | - | - | - |
| Account ID | `account_id` | `integer` | Yes | dbt Cloud account numeric ID |
| Access URL | `access_url` | `string` | Yes | Example: `https://cloud.getdbt.com` |
| Service Token | `service_token` | `string` | Yes (service-token mode) | Saved as a secret |
| Personal Access Token | `personal_access_token` | `string` | Yes (PAT mode) | Saved as a secret |
| GitHub User | `github_user` | `string` | No | Needed when tools clone the dbt project repo |
| GitHub Token | `github_token` | `string` | No | Saved as a secret; used with `github_user` for repo access |
| Bot Name | `bot_name` | `string` | No | Genesis bot that posts Slack notifications |
| Slack Channel | `slack_channel` | `string` | No | Slack channel for dbt Cloud alerts |

<Note>
  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.
</Note>

<Warning>
  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.
</Warning>

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

<Steps>
  <Step title="Cloud Resource Discovery" icon="cloud">
    Explore projects, jobs, runs, environments, and connections across DBT Cloud accounts.
  </Step>

  <Step title="Run Analytics" icon="chart-line">
    Break down model timings, test results, and performance metrics from completed runs.
  </Step>

  <Step title="Context & Config" icon="circle-info">
    Pull project and environment context to power governance and documentation.
  </Step>

  <Step title="Live Monitoring" icon="bell">
    Track job executions in near real time and trigger alerts on failures.
  </Step>

  <Step title="Scalable Listings" icon="list">
    Page through large resource sets with filters for status and size.
  </Step>
</Steps>

## **Input Parameters for Each Function**

### **`dbt_cloud_analyze_run`**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **account\_id** | DBT Cloud account id. | String (required) |
| **run\_id** | The job run id to analyze. | String (required) |
| **api\_token** | DBT Cloud API token. | String (required) |
| **include\_artifacts** | Include run artifacts in the analysis output. | Boolean |
| **detailed\_metrics** | Return granular timing and performance metrics if available. | Boolean |

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`**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **acct\_id** | dbt Cloud account ID. | Integer |
| **access\_url** | dbt Cloud access URL (for example `https://cloud.getdbt.com`). | String |
| **svc\_token** | dbt Cloud API token — service token or personal access token. | String |
| **auth\_type** | Token kind: `service_token` (default) or `personal_access_token`. | String |
| **github\_user** | GitHub user handle for dbt project repo access. | String |
| **github\_token** | GitHub token for dbt project repo access. | String |
| **bot\_name** | Genesis bot that posts Slack notifications. | String |
| **slack\_channel** | Slack channel for dbt Cloud alerts. | String |

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`:

| Value in runtime context | Returned in `content` |
| - | - |
| Secret reference (`secret_*`, `env_*`, or similar) | The reference string unchanged |
| Resolved plaintext token | `<configured>` |

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`**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **account\_id** | DBT Cloud account id. | String (required) |
| **resource\_type** | Resource to list: `projects`, `jobs`, `runs`, `environments`, `connections`. | String (required) |
| **api\_token** | DBT Cloud API token. | String (required) |
| **limit** | Maximum number of results to return. | Integer |
| **offset** | Pagination offset. | Integer |
| **status\_filter** | Optional status filter where supported. | String |

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`**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **account\_id** | DBT Cloud account id. | String (required) |
| **resource\_type** | Type of resource to retrieve. | String (required) |
| **resource\_id** | Unique id of the resource. | String (required) |
| **api\_token** | DBT Cloud API token. | String (required) |
| **include\_related** | Include related objects when available. | Boolean |

#### 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`**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **account\_id** | DBT Cloud account id. | String (required) |
| **api\_token** | DBT Cloud API token. | String (required) |
| **job\_id** | The job id to monitor. If omitted, monitor recent account jobs. | String |
| **monitor\_duration** | Minutes to monitor before stopping. | Integer |
| **alert\_on\_failure** | Send alert events on job failures. | Boolean |

### **`dbt_cloud_run_job`**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **job\_id** | Numeric ID of the dbt Cloud job to start. | Integer (required) |
| **cause** | Short audit reason recorded on the dbt Cloud run. | String (required) |
| **steps\_override** | Optional ordered dbt commands replacing the job commands for one run. | Array of strings |
| **presenter\_incident\_id** | Trusted presenter incident ID for an approval-triggered recovery run. Pass only the ID supplied by the trusted dbt Cloud investigation. | String |
| **presenter\_approved** | Set to `true` only after the presenter authorizes direct remediation through the trusted incident transport. | Boolean (default `false`) |

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`**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **presenter\_incident\_id** | Trusted presenter incident ID whose successful recovery should be verified. | String (required) |
| **job\_id** | Numeric dbt Cloud job ID from the trusted presenter incident. | Integer (required) |

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`)

| Field | Description |
| - | - |
| `success` | Whether verification started or refreshed successfully. |
| `content` | Prover `run_id`, `status`, `verdict`, `finished_at`, comparison evidence when available, and `prior_attempts` when a failed verification is retried. |
| `error` | Why verification could not start or refresh. |

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.

<Tip>
  For large listings, supply **limit** and **offset** to control pagination and avoid hitting rate limits.
</Tip>

## **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.

<Warning>
  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`.
</Warning>

See also [Connections](/docs/Setup/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](/docs/Genbot-Toolkit/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.