Connect PostHog

To connect PostHog to CoIsland, you create a personal API key in PostHog, add it as a PostHog connector with the address of your project, then pick what to watch: a HogQL query, an insight crossing a number, or new exceptions. You do it alone: no admin, no app registration.

CoIsland calls PostHog’s API straight from your Mac: there is no CoIsland server and no CoIsland account. The key stays in your login Keychain, and CoIsland only reads. It works with PostHog Cloud US, Cloud EU and a self-hosted PostHog.

Create a personal API key

1. In PostHog, open Settings › Personal API keys and click Create a personal API key.
2. Label: one you will recognize, such as CoIsland.
3. Organization and project access: limit it to the project you want to watch.
4. Scopes: set these to Read: Project, Query, Insight and Error tracking. User read is optional: with it, Test connector says whose key it is.
5. Create it and copy the key (phx_…). PostHog shows it once.

The project API key (phc_…) only sends events: CoIsland refuses it and asks for a personal key.

Connect PostHog in CoIsland

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

Field	What to enter
Project address	Any address of your project in PostHog, such as https://us.posthog.com/project/12345/insights. CoIsland keeps the host and the project number. An ingestion address (us.i.posthog.com) is changed to its app address. http:// is refused except on localhost
Connector name	What monitors call it. CoIsland suggests posthog-12345
Personal API key	The key you copied

Test connector reads the project, your user, runs SELECT 1 and lists one insight, then says which of Query and Insight read the key lacks. It saves nothing.

Watch PostHog: the three monitor kinds

Kind	What you write	What alerts
HogQL query	A HogQL SELECT	A new row, or a row count crossing a number
Insight threshold	An insight and a limit	Its number going above or below the limit
New exceptions	A lookback and a status	An error tracking issue seen for the first time

HogQL query

Any HogQL SELECT or WITH on your project, through PostHog’s query API. It returns up to 100 rows unless the query sets a LIMIT. Examples in the app:

SELECT event, count() AS n
FROM events
WHERE timestamp > now() - INTERVAL 1 HOUR
GROUP BY event
HAVING n > 1000

SELECT count() AS n
FROM events
WHERE event = '$pageview' AND timestamp > now() - INTERVAL 1 HOUR
HAVING n = 0

The second returns a row only when tracking stops, so it alerts then. New HogQL monitors check every 15 minutes.

Insight threshold

insight:AaVQ8Ijw above:1000
insight:AaVQ8Ijw below:10 series:2

The editor lists your saved insights by name. CoIsland computes the insight as PostHog shows it and reads its single number, or its latest point (the current day or hour, still counting). It alerts once when the number crosses the limit, and again after it came back. The alert page shows the latest points and says Back under once it is inside the limit. Only Trends insights have a number to watch.

New exceptions

lookback:24h
lookback:6h status:resolved

Error tracking issues first seen within the lookback (1h, 6h, 24h or 7d), active unless you pick another status. The card says how many events and users; the alert page adds the page it happened on and the last stack.

A PostHog monitor is a watch file

-- name: Signups spike
-- kind: posthog.insight
-- connector: posthog-12345
-- every: 15m
-- alert: new-rows

insight:AaVQ8Ijw above:1000

-- kind:	Monitor kind
posthog.hogql	HogQL query
posthog.insight	Insight threshold
posthog.exceptions	New exceptions

Troubleshooting PostHog connector errors

• “The personal API key was refused.” The key is wrong, rolled or deleted, or the address is on another PostHog (US, EU or yours). Create a key and edit the connector.
• “Not allowed: API key missing required scope …” Give the key that scope in Settings › Personal API keys, and access to the project.
• “PostHog refused the query: …” A HogQL mistake, in PostHog’s words.
• “Insight … is not a trend with a number to watch.” Pick a Trends insight.
• Rate limited. The query API allows 2,400 requests an hour per project; CoIsland waits and tries again.

Frequently asked questions

Can CoIsland change anything in PostHog?

No. It reads projects, insights and error tracking, and runs HogQL, which PostHog runs read-only. The only POST it sends is to the query API.

Where does CoIsland keep my PostHog key?

In your login Keychain. connectors.json holds the connector’s name and project address, never the key.