REST API (v2 and v3) over Bearer-token / service-token auth for programmatic administration of dbt Cloud - listing and triggering jobs, polling and cancelling runs, downloading run artifacts, and managing accounts, projects, environments, connections, credentials, groups, and users.
openapi: 3.0.1
info:
title: dbt Cloud Administrative API
description: >-
The dbt Cloud Administrative API enables programmatic administration of a dbt
Cloud account. Use it to list and trigger jobs, poll and cancel runs, download
run artifacts, and manage accounts, projects, and environments. This document
models the documented v2 REST surface served from
https://cloud.getdbt.com/api/v2. Requests are authenticated with a Bearer
service token or personal access token. dbt Labs also offers a v3 REST API for
additional resource management, a GraphQL Discovery (Metadata) API at
metadata.cloud.getdbt.com/graphql, and a Semantic Layer API (GraphQL and JDBC).
termsOfService: https://www.getdbt.com/cloud/terms
contact:
name: dbt Labs Support
url: https://docs.getdbt.com/docs/dbt-cloud-apis/overview
version: '2'
servers:
- url: https://cloud.getdbt.com/api/v2
description: dbt Cloud Administrative API v2 (multi-tenant North America). Account-specific
regions use cloud.getdbt.com, emea.dbt.com, au.dbt.com, or a single-tenant host.
security:
- BearerAuthentication: []
tags:
- name: Accounts
description: Account configuration and details.
- name: Projects
description: dbt projects within an account.
- name: Jobs
description: Job definitions and triggering of job runs.
- name: Runs
description: Job run history, status, and lifecycle.
- name: Run Artifacts
description: Artifacts (manifest, catalog, run results) produced by runs.
paths:
/accounts/:
get:
operationId: listAccounts
tags:
- Accounts
summary: List the accounts the authenticated token can access.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AccountListResponse'
/accounts/{account_id}/:
get:
operationId: retrieveAccount
tags:
- Accounts
summary: Retrieve a single account by ID.
parameters:
- $ref: '#/components/parameters/AccountId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AccountResponse'
/accounts/{account_id}/projects/:
get:
operationId: listProjects
tags:
- Projects
summary: List projects in an account.
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectListResponse'
post:
operationId: createProject
tags:
- Projects
summary: Create a project in an account.
parameters:
- $ref: '#/components/parameters/AccountId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectResponse'
/accounts/{account_id}/projects/{id}/:
get:
operationId: retrieveProject
tags:
- Projects
summary: Retrieve a project by ID.
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/PathId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectResponse'
post:
operationId: updateProject
tags:
- Projects
summary: Update a project by ID.
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/PathId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectResponse'
delete:
operationId: destroyProject
tags:
- Projects
summary: Delete a project by ID.
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/PathId'
responses:
'200':
description: OK
/accounts/{account_id}/jobs/:
get:
operationId: listJobs
tags:
- Jobs
summary: List jobs in an account, optionally filtered by project.
parameters:
- $ref: '#/components/parameters/AccountId'
- name: project_id
in: query
schema:
type: integer
description: Filter jobs by project ID.
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JobListResponse'
post:
operationId: createJob
tags:
- Jobs
summary: Create a job in an account.
parameters:
- $ref: '#/components/parameters/AccountId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/JobResponse'
/accounts/{account_id}/jobs/{id}/:
get:
operationId: retrieveJob
tags:
- Jobs
summary: Retrieve a job by ID.
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/PathId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JobResponse'
post:
operationId: updateJob
tags:
- Jobs
summary: Update a job by ID.
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/PathId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JobResponse'
delete:
operationId: destroyJob
tags:
- Jobs
summary: Delete a job by ID.
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/PathId'
responses:
'200':
description: OK
/accounts/{account_id}/jobs/{job_id}/run/:
post:
operationId: triggerJobRun
tags:
- Jobs
summary: Trigger a job to run.
parameters:
- $ref: '#/components/parameters/AccountId'
- name: job_id
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerRunRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RunResponse'
/accounts/{account_id}/runs/:
get:
operationId: listRuns
tags:
- Runs
summary: List runs in an account, with optional filtering and ordering.
parameters:
- $ref: '#/components/parameters/AccountId'
- name: job_definition_id
in: query
schema:
type: integer
description: Filter runs by job ID.
- name: order_by
in: query
schema:
type: string
description: Field to order results by (e.g. -id for most recent first).
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RunListResponse'
/accounts/{account_id}/runs/{id}/:
get:
operationId: retrieveRun
tags:
- Runs
summary: Retrieve a run by ID.
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/PathId'
- name: include_related
in: query
schema:
type: string
description: 'Comma-separated related fields to include (e.g. trigger,job,run_steps).'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RunResponse'
/accounts/{account_id}/runs/{run_id}/cancel/:
post:
operationId: cancelRun
tags:
- Runs
summary: Cancel a run that is queued or in progress.
parameters:
- $ref: '#/components/parameters/AccountId'
- name: run_id
in: path
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RunResponse'
/accounts/{account_id}/runs/{run_id}/artifacts/:
get:
operationId: listRunArtifacts
tags:
- Run Artifacts
summary: List artifact files generated by a completed run.
parameters:
- $ref: '#/components/parameters/AccountId'
- name: run_id
in: path
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ArtifactListResponse'
/accounts/{account_id}/runs/{run_id}/artifacts/{path}:
get:
operationId: retrieveRunArtifact
tags:
- Run Artifacts
summary: Download a specific artifact file (e.g. manifest.json, catalog.json) from a run.
parameters:
- $ref: '#/components/parameters/AccountId'
- name: run_id
in: path
required: true
schema:
type: integer
- name: path
in: path
required: true
schema:
type: string
description: 'Relative artifact path, e.g. manifest.json or run_results.json.'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
components:
securitySchemes:
BearerAuthentication:
type: http
scheme: bearer
description: >-
dbt Cloud service token or personal access token passed in the
Authorization header as 'Authorization: Token <token>' or
'Authorization: Bearer <token>'.
parameters:
AccountId:
name: account_id
in: path
required: true
schema:
type: integer
description: Numeric dbt Cloud account ID.
PathId:
name: id
in: path
required: true
schema:
type: integer
description: Numeric resource ID.
Limit:
name: limit
in: query
schema:
type: integer
maximum: 100
description: Maximum number of results to return (max 100).
Offset:
name: offset
in: query
schema:
type: integer
description: Number of results to skip for pagination.
schemas:
Pagination:
type: object
properties:
count:
type: integer
total_count:
type: integer
StatusMeta:
type: object
properties:
code:
type: integer
is_success:
type: boolean
user_message:
type: string
developer_message:
type: string
Account:
type: object
properties:
id:
type: integer
name:
type: string
plan:
type: string
state:
type: integer
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
AccountResponse:
type: object
properties:
status:
$ref: '#/components/schemas/StatusMeta'
data:
$ref: '#/components/schemas/Account'
AccountListResponse:
type: object
properties:
status:
$ref: '#/components/schemas/StatusMeta'
data:
type: array
items:
$ref: '#/components/schemas/Account'
Project:
type: object
properties:
id:
type: integer
account_id:
type: integer
name:
type: string
connection_id:
type: integer
repository_id:
type: integer
state:
type: integer
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
ProjectResponse:
type: object
properties:
status:
$ref: '#/components/schemas/StatusMeta'
data:
$ref: '#/components/schemas/Project'
ProjectListResponse:
type: object
properties:
status:
$ref: '#/components/schemas/StatusMeta'
data:
type: array
items:
$ref: '#/components/schemas/Project'
extra:
type: object
properties:
pagination:
$ref: '#/components/schemas/Pagination'
JobSettings:
type: object
properties:
threads:
type: integer
target_name:
type: string
JobTriggers:
type: object
properties:
github_webhook:
type: boolean
git_provider_webhook:
type: boolean
schedule:
type: boolean
on_merge:
type: boolean
Job:
type: object
properties:
id:
type: integer
account_id:
type: integer
project_id:
type: integer
environment_id:
type: integer
name:
type: string
description:
type: string
execute_steps:
type: array
items:
type: string
dbt_version:
type: string
state:
type: integer
triggers:
$ref: '#/components/schemas/JobTriggers'
settings:
$ref: '#/components/schemas/JobSettings'
schedule:
type: object
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
JobResponse:
type: object
properties:
status:
$ref: '#/components/schemas/StatusMeta'
data:
$ref: '#/components/schemas/Job'
JobListResponse:
type: object
properties:
status:
$ref: '#/components/schemas/StatusMeta'
data:
type: array
items:
$ref: '#/components/schemas/Job'
extra:
type: object
properties:
pagination:
$ref: '#/components/schemas/Pagination'
TriggerRunRequest:
type: object
required:
- cause
properties:
cause:
type: string
description: Human-readable reason the run was triggered.
git_sha:
type: string
git_branch:
type: string
schema_override:
type: string
dbt_version_override:
type: string
threads_override:
type: integer
steps_override:
type: array
items:
type: string
Run:
type: object
properties:
id:
type: integer
account_id:
type: integer
project_id:
type: integer
job_definition_id:
type: integer
environment_id:
type: integer
status:
type: integer
description: '1=Queued, 2=Starting, 3=Running, 10=Success, 20=Error, 30=Cancelled.'
status_humanized:
type: string
git_branch:
type: string
git_sha:
type: string
is_complete:
type: boolean
is_success:
type: boolean
is_error:
type: boolean
is_cancelled:
type: boolean
href:
type: string
created_at:
type: string
format: date-time
finished_at:
type: string
format: date-time
RunResponse:
type: object
properties:
status:
$ref: '#/components/schemas/StatusMeta'
data:
$ref: '#/components/schemas/Run'
RunListResponse:
type: object
properties:
status:
$ref: '#/components/schemas/StatusMeta'
data:
type: array
items:
$ref: '#/components/schemas/Run'
extra:
type: object
properties:
pagination:
$ref: '#/components/schemas/Pagination'
ArtifactListResponse:
type: object
properties:
status:
$ref: '#/components/schemas/StatusMeta'
data:
type: array
items:
type: string
description: Relative paths of artifact files available for download.