canonical: https://jentic.com/apis/getdbt.com/dbt

# Getdbt dbt Cloud API

dbt Cloud is the hosted environment for dbt, the analytics engineering tool used by data teams to model and transform warehouse data. This page describes a curated, agent-optimized Jentic specification covering 12 operations across accounts, projects, jobs, runs, environments, and connections, including the ability to trigger and cancel runs programmatically. dbt Labs publishes its own OpenAPI documents for the dbt Cloud API in a public GitHub repository, split into separate v2 and v3 files; the Jentic variant keeps the job, run, and project operations an agent calls most in a single document. It is most often used to integrate dbt jobs into orchestration tools, alerting pipelines, and data CI/CD setups.

## For AI agents

Trigger and monitor dbt Cloud transformation jobs, list projects and environments, cancel running jobs, and inspect run metadata for analytics engineering pipelines. Authenticated with personal access tokens or service account tokens.

## Scope

Does not handle dbt source authoring, semantic-layer queries, or warehouse data reads - use for triggering and monitoring dbt Cloud jobs, runs, and project metadata only.

## Capabilities

- Trigger a dbt Cloud job run on demand from an upstream data-loading event
- Monitor a run's status until success or failure to gate downstream pipeline steps
- List jobs within an account to inventory transformation workloads for documentation
- Cancel a long-running job that is blocking a deployment or analytics window
- Retrieve project and environment metadata to drive infrastructure-as-code workflows
- List warehouse connections attached to an account for audit and review

## Use cases

### EL-Triggered Transformation

Modern data stacks load raw data via tools like Fivetran or Airbyte and then transform it with dbt. The dbt Cloud API's trigger endpoint lets the loader call dbt the moment data lands, replacing time-based scheduling with event-driven runs and tightening freshness for downstream dashboards.

Example prompt: On a Fivetran webhook for sync completion, call `POST `/accounts/{account_id}/jobs/{job_id}/run`` and store the returned run ID for monitoring.

### Run Monitoring and Alerting

Data teams want alerts when a dbt run fails or runs unusually long. The API exposes a run-detail endpoint that returns status, duration, and step-level metadata, so a polling job or orchestrator can monitor active runs and emit alerts based on real state rather than scheduled assumptions.

Example prompt: Poll `GET `/accounts/{account_id}/runs/{run_id}`` every 30 seconds until status is success or failure and emit an alert if duration exceeds the SLA.

### Orchestrator-Driven dbt Step

Workflow tools like Airflow, Dagster, or Prefect often need to call dbt as a step in a wider DAG so transformations sit alongside ingestion and reverse ETL. The API supports trigger and run-status calls suitable for an operator to wrap dbt as a first-class workflow step with retry and SLA handling.

Example prompt: From the orchestrator task, call `POST `/accounts/{account_id}/jobs/{job_id}/run``, then poll `GET `/accounts/{account_id}/runs/{run_id}`` and surface the final status to the workflow.

### Agent-Driven Data Operations

An AI agent in a data-ops chat tool can resolve 'rerun the customers job' by discovering the trigger operation through Jentic and executing it. The agent hands off the bearer token management to Jentic and reports back the run ID and status link, so analysts get a single conversational entry point for dbt operations.

Example prompt: Resolve the job ID for the 'customers' job, call `POST `/accounts/{account_id}/jobs/{job_id}/run`` via Jentic, and reply with the run ID and link.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/accounts/{account_id}/jobs/{job_id}/run` | Trigger a job run |
| GET | `/accounts/{account_id}/runs/{run_id}` | Get run details |
| POST | `/accounts/{account_id}/runs/{run_id}/cancel` | Cancel a run |
| GET | `/accounts/{account_id}/jobs` | List jobs |
| GET | `/accounts/{account_id}/projects` | List projects |
| GET | `/accounts/{account_id}/environments` | List environments |
| GET | `/accounts/{account_id}/connections` | List connections |

## Key resources

- **Accounts** — Top-level dbt Cloud accounts owning projects, jobs, and connections.
- **Projects** — dbt projects scoped to an account; hold the modelled transformations.
- **Jobs** — Configured dbt jobs that can be triggered to produce runs.
- **Runs** — Individual job executions with status and metadata.
- **Environments** — Deployment environments such as production or QA.
- **Connections** — Warehouse connections attached to projects.

## Why Jentic

- **Setup:** Wiring dbt Cloud by hand means handling its bearer auth, threading the account id through the v3 job and run paths, and polling run status yourself. Through Jentic you install once, import the dbt Cloud API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** dbt Cloud puts the account id in the URL path (`/accounts/{account_id}/...`), so a rule can pin your agent to one account: it triggers and monitors jobs and reads projects, environments, and connections there. You choose the operations it may call, so cancelling a run is not included unless you add it.
- **Credential handling:** Your dbt Cloud token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'trigger a dbt job run' or 'check the status of a run', and Jentic returns the matching dbt Cloud operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Airbyte** — Open-source data integration platform that loads sources to a warehouse before dbt transforms them.
- **Snowflake** — Cloud data warehouse that dbt Cloud commonly transforms data inside.
- **Prefect** — Workflow orchestration platform that can call dbt Cloud as a step in a wider DAG.

## FAQ

### Which OpenAPI specification does this dbt Cloud API page describe?

A curated, agent-optimized Jentic specification covering 12 dbt Cloud operations across accounts, projects, jobs, runs, environments, and connections. dbt Labs also publishes its own OpenAPI documentation as a two-document set, openapi-v2.yaml and openapi-v3.yaml, listed in its spec repository at https://github.com/dbt-labs/dbt-cloud-openapi-spec; the v3 document covers the administrative surface and points readers to the Discovery API or v2 for job and run endpoints. The Jentic variant keeps the job, run, and project operations together in one document with the input schemas an agent needs to call them. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the dbt Cloud API use?

The dbt Cloud v3 API uses HTTP Bearer authentication with a personal access token or a service account token. Through Jentic, the token is stored encrypted in the vault and injected as `Authorization: Bearer …` at execution time.

### Can I trigger a dbt Cloud job programmatically?

Yes. Call `POST `/accounts/{account_id}/jobs/{job_id}/run`` with the account and job ID. The response includes the run ID, which you then monitor via the runs endpoint.

### Can I cancel a running dbt job through the API?

Yes. Call `POST `/accounts/{account_id}/runs/{run_id}/cancel`` with the account and run ID to stop a job that is in progress.

### How do I monitor a dbt run through Jentic?

Search Jentic for `get a dbt Cloud run status`, load the schema for `GET `/accounts/{account_id}/runs/{run_id}``, and execute with the run ID. Jentic injects the bearer token automatically.

### Does the dbt Cloud API expose model-level results or test failures?

The v3 endpoints in this spec expose run metadata at the run level. For model-level artifacts and tests, you typically combine the run-trigger and status endpoints with dbt's run results artifact downloads or the dedicated metadata API.

### Can I limit what my agent is allowed to do with the dbt Cloud API?

Yes. Because you run Jentic One yourself, your own rules decide which dbt Cloud operations and which token the agent may use. Since dbt Cloud puts the account ID in the URL path, you can pin the agent to a single account and grant only the operations you want, such as triggering a job run, reading run status, and listing projects, environments, and connections. Cancelling a run is not included unless you add that operation to the agent's allowed set.