Linking dbt as a source
This source is currently in alpha. The interface and available tables may change.
The dbt connector syncs metadata from the dbt platform (dbt Cloud) into PostHog – accounts, projects, environments, job definitions, users, and the full job run history – so you can analyze pipeline reliability, run durations, and failure rates alongside your product data.
Prerequisites
You need a dbt platform account and an API token:
- A service account token (recommended) – available on Team and Enterprise plans under Account settings > API tokens > Service tokens. Read-only access to the resources you want to sync is enough.
- A personal access token also works, under Account settings > API tokens > Personal tokens.
Syncing the users table requires a token with user read permissions, which many read-only tokens lack. It's deselected by default.
Adding a data source
- In PostHog, go to the Sources tab of the data pipeline section.
- Click + New source and click Link next to this source.
- Enter your credentials (see Configuration below) and click Next.
- Select the tables you want to sync, choose a sync method and frequency, then click Import.
Once the syncs are complete, you can start querying this data in PostHog.
When linking dbt, you'll need:
- Account ID – the number after
/deploy/in your dbt URL. - API token – a service account token or personal access token.
- Region – where your dbt account is hosted: US (
cloud.getdbt.com), EMEA (emea.dbt.com), or APAC (au.dbt.com). - Custom base URL (optional) – for cell-based or single-tenant deployments (for example
https://ab123.us1.dbt.com). When set, it overrides the region.
Sync modes
Each table can be synced in one of several modes, depending on what the source supports:
- Webhook (when available) – the source pushes changes to PostHog in real time. Fastest freshness, lowest ongoing cost, and the only mode that reliably captures updates and deletes.
- Incremental – only new or updated rows are synced on each run, using a cursor field (such as an
updated_attimestamp). Cheaper than a full refresh, but deletes aren't captured. - Append only – new rows are appended using a cursor field; existing rows are never updated. Ideal for immutable, append-only tables like event logs.
- Full refresh – the whole table is reloaded on every sync. Use it when a table has no reliable cursor or when you need deletions reflected.
See sync methods for a full explanation of how each mode works and how to choose between them.
The runs table supports incremental sync on created_at: each sync fetches runs newest-first and stops once it reaches already-synced rows, with a 24 hour overlap so recently created runs pick up their final status. The other tables are small and sync as a full refresh.
Configuration
| Option | Type | Required |
|---|---|---|
Account ID | text | Yes |
API token | password | Yes |
Region | select | Yes |
Custom base URL (optional) | text | No |
Supported tables
| Table | Description | Sync method | Incremental field | Primary key |
|---|---|---|---|---|
accounts | dbt platform accounts the API token has access to | Full refresh | — | — |
projects | dbt projects in the account | Full refresh | — | — |
environments | Development and deployment environments across the account's projects | Full refresh | — | — |
jobs | Job definitions (scheduled and triggered dbt executions) across the account | Full refresh | — | — |
users | Users with access to the account. Requires a token with user read permissions | Full refresh | — | — |
runs | Job run history, including status, timing, and git metadata | Incremental, Full refresh | created_at | — |
Troubleshooting
If your sync is failing or data looks wrong, see the Data warehouse troubleshooting guide. If that doesn't help, contact support – we're happy to help.