​

dbt Cloud API Configuration

​

Prerequisites Checklist

​

Step 1: Get dbt Cloud API Token

​

1.1 Create API Token

1. Log in to dbt Cloud (cloud.getdbt.com)
2. Click your profile icon (top right)
3. Go to Account Settings
4. Click API Access in the left sidebar
5. Click + Create Token
6. Configure the token:
   • Description: Collate Integration
   • Permission: Account Viewer
7. Click Save
8. Copy the token immediately - you won’t see it again!

dbt_cloud_abc123def456ghi789jkl...

​

1.2 Find Your Account ID

https://cloud.getdbt.com/accounts/12345/projects/...
                                 ^^^^^
                         This is your Account ID

export DBT_CLOUD_TOKEN="your-token-here"

curl -H "Authorization: Token ${DBT_CLOUD_TOKEN}" \
     https://cloud.getdbt.com/api/v2/accounts/ | jq '.data[].id'

​

1.3 Identify Your dbt Cloud Region

​

1.4 (Optional) Get Project/Job IDs

• Account ID: In URL: https://cloud.getdbt.com/#/accounts/{ACCOUNT_ID}/...
• Project ID: Go to Account Settings → Projects, click a project, ID is in the URL
• Job ID: Go to Deploy → Jobs, click a job, ID is in the URL

export ACCOUNT_ID="12345"

curl -H "Authorization: Token ${DBT_CLOUD_TOKEN}" \
     https://cloud.getdbt.com/api/v2/accounts/${ACCOUNT_ID}/projects/ | \
     jq '.data[] | {id, name}'

{
  "id": 98765,
  "name": "analytics"
}

curl -H "Authorization: Token ${DBT_CLOUD_TOKEN}" \
     https://cloud.getdbt.com/api/v2/accounts/${ACCOUNT_ID}/jobs/ | \
     jq '.data[] | {id, name, project_id}'

{
  "id": 54321,
  "name": "Daily Production Run",
  "project_id": 98765
}

​

Step 2: Configure Collate

​

Configuration

1. Go to Settings → Services → Database Services
2. Click on your database service (e.g., “production-snowflake”)
   • Important: Must match the database dbt connects to
3. Go to the Ingestion tab
4. Click Add Ingestion
5. Select dbt from the dropdown

• Both empty: Uses most recent successful run from any job in the account
• Project ID provided: Uses most recent run from that specific project
• Both provided: Uses most recent run from that specific job

1. Click Test Connection
   • Should show: ✓ API connectivity, ✓ Account access, ✓ Recent run found
2. If successful, click Deploy
3. Click Run to trigger immediately

​

Verification

​

Verification Checklist

​

Best Practices

​

Ensure Jobs Generate All Artifacts

dbt run           # Generates manifest.json
dbt test          # Generates run_results.json with test results
dbt docs generate # Generates catalog.json with column descriptions

1. Go to dbt Cloud → Jobs
2. Click on your job
3. Go to Settings → Commands
4. Confirm all three commands are present

​

Schedule Alignment

​

API Rate Limits

• 100 requests per minute per API token

​

Troubleshooting

​

Debug Commands

# Test API connectivity
curl -H "Authorization: Token ${DBT_CLOUD_TOKEN}" \
     https://cloud.getdbt.com/api/v2/accounts/${ACCOUNT_ID}/ | jq '.'

# Get most recent successful run (what Collate will use)
curl -H "Authorization: Token ${DBT_CLOUD_TOKEN}" \
     "https://cloud.getdbt.com/api/v2/accounts/${ACCOUNT_ID}/runs/?status=10&order_by=-finished_at&limit=1" | \
     jq '.data[0] | {id, job_id, finished_at, status_humanized}'

# Download manifest from run
curl -H "Authorization: Token ${DBT_CLOUD_TOKEN}" \
     "https://cloud.getdbt.com/api/v2/accounts/${ACCOUNT_ID}/runs/${RUN_ID}/artifacts/manifest.json" | \
     jq '.metadata.dbt_version'

​

Next Steps

• Configure dbt Workflow
• dbt Troubleshooting
• Ingest dbt Descriptions