dbt Cloud API v2
dbt Cloud API v2
Your unique account prefix. Can be found on your account settings page.
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.
Authentication
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
Pagination
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 filteredfilters: {...},// The order of the resultsorder_by: "id",// The pagination statepagination: {// The number of records returned in this responsecount: 5,// The total number of available recordstotal_count: 10,}}}
Example request
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>'