A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The dbt API is how an app or AI agent works with a dbt account: triggering a job run, reading a run's status and downloading its artifacts, listing and creating jobs, and managing projects, environments, and connections. Access is granted through an API token sent in an Authorization header, and the token's permission set decides which areas it can read or write and which account it reaches. dbt can also push an event when a scheduled job run starts, finishes, or errors, so an app is told rather than having to ask.
How an app or AI agent connects to dbt determines what it can reach. There are two main routes, the Administrative API for managing an account and triggering work, and a hosted MCP server for reading metadata, each governed by the token behind it and the permissions that token carries.
The Administrative API manages a dbt account and triggers work, covering jobs, runs, artifacts, projects, environments, connections, repositories, users, groups, service tokens, and webhook subscriptions. It runs two numbered versions, v3 for the newest endpoints and v2 for jobs, runs, and artifacts. The access URL is specific to the account's region.
dbt publishes a first-party MCP server at github.com/dbt-labs/dbt-mcp. A remote server hosted on the dbt platform gives read access to metadata and the Semantic Layer over an HTTP connection, while a local server installed with uvx adds dbt CLI commands such as run, build, and test. It lets an agent reach dbt project context through the Model Context Protocol.
A webhook subscription delivers an event when a scheduled job run starts, finishes, or errors, posting the payload to a registered URL. Each delivery carries an HMAC-SHA256 signature in the Authorization header, computed from a shared secret, so the receiver can confirm it came from dbt.
The Discovery API is a separate GraphQL metadata API that reads the state and health of a dbt project, such as models, tests, and freshness. It is read-only and documents its own limit of 200 requests per minute per IP address.
A service account token belongs to the account rather than a user, and is assigned one of dbt's named permission sets directly, such as Account Admin, Job Admin, or Metadata Only. It suits a system integration that does not act on behalf of one person, and keeps working when individuals leave.
A personal access token belongs to a user and inherits that user's exact role and project access, so its reach matches that person's. Account-scoped personal access tokens are the modern replacement for the deprecated user API keys, which no longer work.
The dbt Cloud Administrative API is split into areas an agent can act on, such as jobs, runs, projects, environments, connections, and account membership. Each area has its own methods, and the permission set on the token decides which it can reach.
List, read, create, update, and delete jobs, the saved sets of dbt commands that an account runs on a schedule or on demand.
Trigger a job to start a run, list and read runs, cancel a run, retry a failed run, and download a finished run's artifacts.
List, read, create, update, and delete projects, the top-level container for an account's connections, repositories, environments, and jobs.
List, read, create, update, and delete the environments a project runs in, such as development and production.
List, read, create, and delete the warehouse connections and Git repositories that a project is wired to.
List and read users, list, create, and update groups, and list and create the service tokens that grant API access.
List, read, create, update, and delete the subscriptions that push job run events to a registered URL.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
JobsList, read, create, update, and delete jobs, the saved sets of dbt commands that an account runs on a schedule or on demand.5 | ||||||
| GET | /api/v2/accounts/{account_id}/jobs/ | List the jobs in an account. | read | Job Viewer | Current | |
A personal access token reads jobs the user can see. A service account token needs a set that grants job read, such as Job Viewer or Account Viewer. Acts onjob Permission (capability) Job ViewerVersionAvailable since the API’s base version Webhook eventNone Rate limit100 records per request SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/accounts/{account_id}/jobs/{id}/ | Retrieve a single job by ID. | read | Job Viewer | Current | |
Service account token needs a set that grants job read, such as Job Viewer or Account Viewer. Acts onjob Permission (capability) Job ViewerVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/accounts/{account_id}/jobs/ | Create a job in a project. | write | Job Admin | Current | |
Creating or changing jobs needs a set with write on jobs, such as Job Admin or Account Admin. Acts onjob Permission (capability) Job AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/accounts/{account_id}/jobs/{id}/ | Update an existing job. | write | Job Admin | Current | |
The v2 update is a POST to the job ID, not a PATCH. Needs a set with write on jobs, such as Job Admin. Acts onjob Permission (capability) Job AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/accounts/{account_id}/jobs/{id}/ | Delete a job. | write | Job Admin | Current | |
Deleting a job removes its schedule and history reference. Needs a set with write on jobs, such as Job Admin. Acts onjob Permission (capability) Job AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
RunsTrigger a job to start a run, list and read runs, cancel a run, retry a failed run, and download a finished run's artifacts.7 | ||||||
| POST | /api/v2/accounts/{account_id}/jobs/{job_id}/run/ | Trigger a job to start a run, returning the new run's ID. | write | Job Runner | Current | |
If the job is already running, the new run is enqueued and starts after the current one finishes. Needs a set that can run jobs, such as Job Runner, Job Admin, or Account Admin. Acts onrun Permission (capability) Job RunnerVersionAvailable since the API’s base version Webhook event job-run-startedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/accounts/{account_id}/jobs/{job_id}/rerun/ | Retry a failed job, starting a new run from the point it failed. | write | Job Runner | Current | |
Needs a set that can run jobs, such as Job Runner, Job Admin, or Account Admin. Acts onrun Permission (capability) Job RunnerVersionAvailable since the API’s base version Webhook event job-run-startedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/accounts/{account_id}/runs/ | List the runs in an account, with filters such as job and status. | read | Job Viewer | Current | |
Service account token needs a set that grants run read, such as Job Viewer or Account Viewer. Acts onrun Permission (capability) Job ViewerVersionAvailable since the API’s base version Webhook eventNone Rate limit100 records per request SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/accounts/{account_id}/runs/{id}/ | Retrieve a single run by ID, including its current status. | read | Job Viewer | Current | |
Polling this endpoint is how a run's progress is followed without a webhook. Needs a set that grants run read. Acts onrun Permission (capability) Job ViewerVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/accounts/{account_id}/runs/{run_id}/cancel/ | Cancel a run that is in progress. | write | Job Runner | Current | |
Cancelling stops real work against the warehouse. Needs a set that can run jobs, such as Job Runner or Job Admin. Acts onrun Permission (capability) Job RunnerVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/accounts/{account_id}/runs/{run_id}/artifacts/ | List the artifact files produced by a finished run. | read | Job Viewer | Current | |
Artifacts are available only after the run completes. Needs a set that grants run read. Acts onartifact Permission (capability) Job ViewerVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/accounts/{account_id}/runs/{run_id}/artifacts/{remainder} | Download a single artifact from a finished run, such as manifest.json, catalog.json, or run_results.json. | read | Metadata Only | Current | |
The Metadata Only set is enough to read artifacts and other project metadata without reaching the rest of the account; Job Viewer also works. Acts onartifact Permission (capability) Metadata OnlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ProjectsList, read, create, update, and delete projects, the top-level container for an account's connections, repositories, environments, and jobs.4 | ||||||
| GET | /api/v3/accounts/{account_id}/projects/ | List the projects in an account. | read | Account Viewer | Current | |
Service account token needs a set that grants read across the account, such as Account Viewer or Account Admin. Acts onproject Permission (capability) Account ViewerVersionAvailable since the API’s base version Webhook eventNone Rate limit100 records per request SourceOfficial documentation ↗ | ||||||
| GET | /api/v3/accounts/{account_id}/projects/{id}/ | Retrieve a single project by ID. | read | Account Viewer | Current | |
Needs a set that grants account read, such as Account Viewer. Acts onproject Permission (capability) Account ViewerVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v3/accounts/{account_id}/projects/ | Create a project in an account. | write | Account Admin | Current | |
Creating projects is account-level write, which needs Account Admin. Acts onproject Permission (capability) Account AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v3/accounts/{account_id}/projects/{id}/ | Delete a project and everything inside it. | write | Account Admin | Current | |
Deleting a project removes its connections, repositories, environments, and jobs. Needs Account Admin. Acts onproject Permission (capability) Account AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
EnvironmentsList, read, create, update, and delete the environments a project runs in, such as development and production.3 | ||||||
| GET | /api/v3/accounts/{account_id}/projects/{project_id}/environments/ | List the environments in a project. | read | Account Viewer | Current | |
Needs a set that grants account read, such as Account Viewer. Acts onenvironment Permission (capability) Account ViewerVersionAvailable since the API’s base version Webhook eventNone Rate limit100 records per request SourceOfficial documentation ↗ | ||||||
| POST | /api/v3/accounts/{account_id}/projects/{project_id}/environments/ | Create an environment in a project. | write | Account Admin | Current | |
Changing where a project runs is account-level write, which needs Account Admin. Acts onenvironment Permission (capability) Account AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v3/accounts/{account_id}/projects/{project_id}/environments/{id}/ | Update an environment. | write | Account Admin | Current | |
The v3 update is a POST to the environment ID. Needs Account Admin. Acts onenvironment Permission (capability) Account AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Connections & repositoriesList, read, create, and delete the warehouse connections and Git repositories that a project is wired to.4 | ||||||
| GET | /api/v3/accounts/{account_id}/projects/{project_id}/connections/ | List the warehouse connections in a project. | read | Account Viewer | Current | |
Connection records describe how a project reaches the warehouse. Needs a set that grants account read. Acts onconnection Permission (capability) Account ViewerVersionAvailable since the API’s base version Webhook eventNone Rate limit100 records per request SourceOfficial documentation ↗ | ||||||
| POST | /api/v3/accounts/{account_id}/projects/{project_id}/connections/ | Create a warehouse connection in a project. | write | Account Admin | Current | |
Wiring a project to a warehouse is account-level write, which needs Account Admin. Acts onconnection Permission (capability) Account AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v3/accounts/{account_id}/projects/{project_id}/repositories/ | List the Git repositories connected to a project. | read | Account Viewer | Current | |
Needs a set that grants account read; Git Admin covers repository management. Acts onrepository Permission (capability) Account ViewerVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v3/accounts/{account_id}/projects/{project_id}/repositories/ | Connect a Git repository to a project. | write | Git Admin | Current | |
Connecting a repository changes the code a project runs. The Git Admin set is the targeted permission; Account Admin also covers it. Acts onrepository Permission (capability) Git AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Users, groups & tokensList and read users, list, create, and update groups, and list and create the service tokens that grant API access.5 | ||||||
| GET | /api/v3/accounts/{account_id}/users/ | List the users in an account. | read | Account Viewer | Current | |
Returns people's names and email addresses. Needs a set that grants account read, such as Account Viewer or Security Admin. Acts onuser Permission (capability) Account ViewerVersionAvailable since the API’s base version Webhook eventNone Rate limit100 records per request SourceOfficial documentation ↗ | ||||||
| GET | /api/v3/accounts/{account_id}/groups/ | List the permission groups in an account. | read | Account Viewer | Current | |
Groups map members to roles and project access. Needs a set that grants account read. Acts ongroup Permission (capability) Account ViewerVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v3/accounts/{account_id}/groups/ | Create a permission group. | write | Security Admin | Current | |
Changing who has access to what is a security action. Needs Security Admin or Account Admin. Acts ongroup Permission (capability) Security AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v3/accounts/{account_id}/service-tokens/ | List the service tokens in an account. | read | Security Admin | Current | |
Lists token names and permission sets, not the secret values. Needs Security Admin or Account Admin. Acts onservice token Permission (capability) Security AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v3/accounts/{account_id}/service-tokens/ | Create a service token and assign it permission sets. | write | Security Admin | Current | |
Mints a new credential that can call the API; the secret is returned once at creation. Needs Security Admin or Account Admin. Acts onservice token Permission (capability) Security AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Webhook subscriptionsList, read, create, update, and delete the subscriptions that push job run events to a registered URL.4 | ||||||
| GET | /api/v3/accounts/{account_id}/webhooks/subscriptions | List the webhook subscriptions in an account. | read | Account Viewer | Current | |
Needs a set that grants account read, such as Account Viewer. Acts onwebhook subscription Permission (capability) Account ViewerVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v3/accounts/{account_id}/webhooks/subscriptions | Create a webhook subscription for one or more job run events. | write | Account Admin | Current | |
The subscription chooses among job.run.started, job.run.completed, and job.run.errored, and dbt returns an HMAC secret used to sign each delivery. Needs Account Admin. Acts onwebhook subscription Permission (capability) Account AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v3/accounts/{account_id}/webhooks/subscription/{subscription_id} | Update a webhook subscription. | write | Account Admin | Current | |
Changes which events are sent or where they go. Needs Account Admin. Acts onwebhook subscription Permission (capability) Account AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v3/accounts/{account_id}/webhooks/subscription/{subscription_id} | Delete a webhook subscription. | write | Account Admin | Current | |
Stops the chosen job run events from being delivered. Needs Account Admin. Acts onwebhook subscription Permission (capability) Account AdminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
dbt can notify an app or AI agent when a scheduled job run starts, finishes, or errors, instead of the app repeatedly asking. dbt posts the event to a subscription URL that has been registered, signed so the receiver can confirm it came from dbt.
| Event | What it signals | Triggered by |
|---|---|---|
job.run.started | Fires when a scheduled job run starts. | /api/v2/accounts/{account_id}/jobs/{job_id}/run//api/v2/accounts/{account_id}/jobs/{job_id}/rerun/ |
job.run.completed | Fires when a scheduled job run finishes, whether it succeeded or failed. | /api/v2/accounts/{account_id}/jobs/{job_id}/run//api/v2/accounts/{account_id}/jobs/{job_id}/rerun/ |
job.run.errored | Fires when a scheduled job run errors. | /api/v2/accounts/{account_id}/jobs/{job_id}/run//api/v2/accounts/{account_id}/jobs/{job_id}/rerun/ |
dbt limits how much an app or AI agent can read back in one call, and caps how fast it can call overall. List methods return at most 100 records per request, and going too fast returns an error to back off.
dbt caps how much each list method returns and how fast an account can call overall. Since 1 December 2023, every list or GET method on the Administrative API returns at most 100 records per request on multi-tenant accounts, and a request asking for more returns an error, so results past 100 must be paged with the limit and offset query parameters. dbt does not publish an exact requests-per-minute figure for the Administrative API; going too fast returns an HTTP 429 Too Many Requests, which should be handled by backing off and retrying. The Discovery API, a separate metadata API, documents its own limit of 200 requests per minute per IP address.
List endpoints use offset pagination through the limit and offset query parameters. The limit parameter tops out at 100 on multi-tenant accounts, which is also the default ceiling, and offset moves the window forward. A list response includes an extra.pagination object reporting the total count and the page size, which is used to walk through the remaining pages.
Requests and responses are JSON. The main size constraint is the 100-record cap on list methods rather than a byte limit. Run artifacts, the manifest, catalog, and run results files, are fetched individually by name from a finished run and can be large, so they are downloaded one file at a time rather than inline in a list.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | The API token is missing, malformed, or invalid. This includes sending the token without the required Token or Bearer prefix in the Authorization header. | Send a valid token as 'Authorization: Token |
| 403 | Forbidden | The token is valid but its permission set does not allow the action, or the account is reached from an IP address that is restricted. | Use a token whose permission set covers the action, or call from an allowed IP address. |
| 404 | Not Found | The resource does not exist, or the token cannot see it within the account it is scoped to, such as a wrong account, project, job, or run ID in the path. | Confirm the account ID and resource ID in the path, and that the token is scoped to that account. |
| 429 | Too Many Requests | The account is calling the API too fast and has hit a rate limit. A list method asking for more than 100 records also returns an error. | Back off and retry, and page list results with the limit and offset query parameters to stay within 100 per request. |
dbt runs two numbered versions of the Administrative API side by side. Version 3 is the recommended version with the newest endpoints, while version 2 still carries the jobs, runs, and artifacts methods that have not yet moved across.
Version 3 is the recommended version of the Administrative API and holds the newest endpoints, including projects, environments, connections, repositories, users, groups, service tokens, and webhook subscriptions. Not every v2 route has been moved across, so the jobs, runs, and artifacts endpoints still live in version 2, and an integration commonly calls both versions together.
From 1 December 2023, every list or GET method on the Administrative API v2 and v3 returns at most 100 records per request on multi-tenant accounts. A request that asks for more returns an error, so larger result sets must be paged with the limit and offset query parameters. The cap does not apply to single-tenant instances. The change was first announced in the March 2023 release notes and took effect on 1 December 2023.
Version 2 is the older version of the Administrative API. It still carries the jobs, runs, and artifacts endpoints that have not yet moved to version 3, so it remains in active use alongside version 3. In version 2 a resource update is a POST to the resource ID rather than a PATCH.
An integration can call v2 and v3 endpoints together, since the two versions cover different methods.
dbt platform release notes ↗Bollard AI sits between a team's AI agents and dbt. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.