Genesis Data Agent's Toolkit
DBT Cloud Tools
Explore, monitor, and analyze DBT Cloud projects, jobs, runs, and environments through authenticated API calls.
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
dbt_cloud_analyze_run: Analyze a specific run for timings, test outcomes, artifacts, and performance signals.dbt_cloud_context: Retrieve account, project, and environment context including connections and settings.dbt_cloud_list: List resources such as projects, jobs, runs, environments, and connections with pagination.dbt_cloud_get: Fetch detailed information for a single resource by type and id.dbt_cloud_monitor: Poll job execution for a period and emit real time status updates and alerts.
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
| 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 |
dbt_cloud_context
| Name | Definition | Format |
|---|---|---|
| account_id | DBT Cloud account id. | String (required) |
| api_token | DBT Cloud API token. | String (required) |
| project_id | Project id for scoped context. | String |
| environment_id | Environment id for scoped context. | String |
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 |
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 |
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 |
For large listings, supply limit and offset to control pagination and avoid hitting rate limits.
Use Cases
- Production Run Monitoring Track nightly jobs, emit alerts on failure, and post summaries to Slack.
- Performance Analysis Identify slow models by timing breakdowns and compare runs week over week.
- Ops Dashboards Feed run status and duration metrics into centralized observability tools.
- Governance & Docs Pull project and environment context for documentation and audits.
- Incident Automation On failure, fetch logs and artifacts, open a ticket, and notify owners.
Workflow/How It Works
- Authenticate with an account level api_token.
- Discover resources using
dbt_cloud_list, or get details viadbt_cloud_get. - Monitor active jobs with
dbt_cloud_monitorfor live status. - Analyze completed executions using
dbt_cloud_analyze_runto extract timings, tests, and artifacts. - Act on insights by notifying teams, updating tickets, or storing reports.
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
- Use account scoped api_token with permissions for the target resources.
- 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 API tokens securely and rotate them regularly. Never embed tokens in source files or logs.
Limitations or Notes
- Requires an active DBT Cloud subscription and API access.
- API rate limits apply and vary by plan.
- Monitoring granularity depends on DBT Cloud polling frequency.
- Very large result sets require pagination to avoid timeouts.
- Historical retention and artifact availability may be limited by account settings.
- Cross account resource access needs explicit permissions.
Output
- Run Analysis: Model timings, tests, artifacts, and summary metrics.
- 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.