Connect dbt

To connect dbt to CoIsland, you create a personal access token in dbt, add it as a dbt connector with your account’s address, then pick what to watch: failed job runs, runs that take too long, or stale sources. You do it alone: no account admin and no service token.

CoIsland calls dbt’s Admin API straight from your Mac. The token stays in your login Keychain, and CoIsland only reads runs, jobs and their artifacts.

Create a personal access token

1. In dbt, open Account settings › API tokens › Personal tokens.
2. Click Create personal access token, name it CoIsland, Save, and copy it. dbt shows it once.

Any user with a Developer, Read-only or IT license can create one. It has your role’s access, in this account only: with several dbt accounts, create one per account. Service tokens need an account admin; CoIsland does not ask for one.

Connect dbt in CoIsland

1. Open Settings › Connectors and click + (Add Connector).
2. Choose dbt, fill in the fields, then click Test connector.
3. Click Add Connector.

Field	What to enter
Access URL	Your account’s address: Account settings › Account information › Access URLs, such as https://ab123.us1.dbt.com, https://cloud.getdbt.com or https://emea.dbt.com. Paste any dbt page’s address instead and the account ID comes with it
Account ID	The number after /deploy/ in any dbt page’s address. Leave it empty when the address has it
Connector name	What monitors call it. CoIsland suggests dbt- and the account ID
Personal access token	The token you copied

Test connector reads the account and lists its jobs. “No jobs visible” usually means the wrong account ID, or a role that reaches no project.

Watch dbt: the three monitor kinds

Kind	What you write	What alerts
Failed job runs	Jobs, results and a lookback	A run that ended in error (or cancelled)
Long runs	Jobs and a time	A run taking longer than that
Source freshness	Jobs and results	A source stale in the job’s latest freshness check

The editor lists your jobs by name as you type; none picked is every job you can see.

Failed job runs

lookback:24h
job:123456 status:error,cancelled lookback:7d

Each run that ends in error within the lookback (6h, 24h, 3d or 7d) alerts once; a rerun is a new run and alerts again. The alert page shows the run’s steps and the last lines of the step that failed. New monitors check every 5 minutes.

Long runs

job:123456 over:1h

Runs of the last day that have been running, or ran, longer than over: (5m to 24h). A running one alerts as it crosses the limit, once.

Source freshness

status:error,runtime-error
job:123456 status:error,warn

CoIsland reads each job’s latest run that checked freshness (a dbt source freshness step, or a job with Run source freshness on) and its sources.json. A source in the results picked alerts once; fresh again, it leaves, and alerts again if it goes stale. The alert page says Fresh once the latest check passes.

A dbt monitor is a watch file

-- name: Nightly build failed
-- kind: dbtcloud.runs
-- connector: dbt-12345
-- every: 5m
-- alert: new-rows

job:123456 lookback:24h

-- kind:	Monitor kind
dbtcloud.runs	Failed job runs
dbtcloud.long-runs	Long runs
dbtcloud.freshness	Source freshness

Troubleshooting dbt connector errors

• “The token was refused.” It was revoked, or made in another account: a personal access token works in one account only.
• “Not allowed: …” Your role does not reach that project or job.
• “Job … was not found, or this token cannot see it.” Check the job ID and your access.
• Rate limited. The Admin API allows 5,000 requests a minute per account; after a 429, dbt asks for a 5-minute pause, which CoIsland respects.

Frequently asked questions

Can CoIsland start, cancel or rerun jobs?

No. It only reads runs, jobs and artifacts.

Does it work outside North America?

Yes. Use your account’s access URL: EMEA, APAC, cell-based and single-tenant accounts all serve the Admin API there.

Where does CoIsland keep my dbt token?

In your login Keychain. connectors.json holds the connector’s name, access URL and account ID, never the token.