Skip to main content

dbt Cloud API v2

Overview
Endpoints
Accounts
Connections
Environments
Invites
Jobs
Licenses
Notifications
Permissions
Projects
Repositories
Runs
Users
powered by Stoplight

dbt Cloud API v2

v2.0.0
API Base URL
Production (US):https://cloud.getdbt.com/
Production (US):https://{account_prefix}.us1.dbt.com/
account_prefix
string

Your unique account prefix. Can be found on your account settings page.

Default:
ab123
Production (Europe):https://emea.dbt.com/
Production (AU):https://au.dbt.com/

How to use this API

The dbt Cloud API v2 contains endpoints for enqueuing runs from a job, polling for run progress, and downloading artifacts after jobs have completed running. For operational endpoints to create, modify, and delete objects in dbt Cloud, consider using API v3

The API docs are generated from an openapi spec defined in the dbt-cloud-openapi-spec repository. If you find issues in these docs or have questions about using the dbt Cloud API, please open an issue in the dbt-cloud-openapi-spec repo or contact support@getdbt.com.

To authenticate an application with the dbt Cloud API, navigate to the Account Settings page and go to Personal Tokens from the left sidebar. Create one if you don't have one already. If you cannot access this page, confirm that your dbt Cloud account has access to the API, and that you are using the hosted version of dbt Cloud. If dbt Cloud is running inside of a VPC in an Enterprise account, contact your account manager for help finding your account-scoped Personal Access Token.

Once you've found your Personal Access Token (PAT) for your account, use it in the Authorization header of requests to the dbt Cloud API. Be sure to include the Token prefix in the Authorization header, or the request will fail with a "401 Unauthorized" error.

Note: Bearer can be used in place of Token in the Authorization header. Both syntaxes are equivalent.

Headers

Accept: application/json
Authorization: Token <your token>

All top-level API resources support bulk fetches using the "list" or GET API methods. These API methods accept limit and offset query parameters that you can use together to paginate results and return a subset of those results.

  • Offset: Specifies how many records to skip. Can be an integer 0 and higher.
  • Limit: Specifies the maximum records you want to retrieve in a single request. Can be an integer up to 100. This limit makes responses easier to handle for servers and people.

Endpoints that support pagination include some useful extra information about the pagination state. For example:

{
data: [...],
extra: {
// How the results were filtered
filters: {...},
// The order of the results
order_by: "id",
// The pagination state
pagination: {
// The number of records returned in this response
count: 5,
// The total number of available records
total_count: 10,
}
}
}

The following example uses the list projects endpoint to list the projects that your token is authorized to access. This request skips the first 10 projects and lists the next 10 projects. Be sure to replace <YOUR_TOKEN> in the Authorization header with your actual API token and <YOUR_ACCOUNT_ID> with your actual account ID.

curl --request GET \
--url 'https://cloud.getdbt.com/api/v3/accounts/<YOUR_ACCOUNT_ID>/projects/?limit=10&offset=5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token <YOUR_TOKEN>'