Generate a dbt Cloud API token (Service Token recommended) from the Account Settings page; store it as YOUR_DBT_TOKEN.
Send POST https://cloud.getdbt.com/api/v2/accounts/{account_id}/jobs/{job_id}/run/ with header Authorization: Token YOUR_DBT_TOKEN and a JSON body such as {"cause": "triggered by agent"}.
The response contains a data.id field — this is the run ID; capture it for polling.
Poll GET https://cloud.getdbt.com/api/v2/accounts/{account_id}/runs/{run_id}/ with the same auth header until data.status is 10 (success) or 20 (error) or 30 (cancelled).
On failure, inspect data.status_message and retrieve step-level details from GET /api/v2/accounts/{account_id}/runs/{run_id}/artifacts/ to fetch manifest or run_results.json.
Known gotchas
dbt Cloud status codes are integers, not strings: 1=queued, 3=running, 10=success, 20=error, 30=cancelled — do not compare against string values.
The job must be enabled and the environment it targets must have a valid connection; a misconfigured environment causes the run to fail immediately with a connection error.
Rate limits apply to the v2 API; implement exponential backoff when polling to avoid 429 responses.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp