# Connect PostHog

> Monitor PostHog from your Mac's notch. A HogQL query that finds something, an insight crossing a number or an exception seen for the first time reaches you without opening a dashboard.

Source: https://coisland.app/docs/connect-posthog/

## What you need

- **You need:** Personal API key, from Settings › Personal API keys
- **The form asks:** Project address, Connector name, Personal API key
- **You can watch:** HogQL query, Insight threshold, New exceptions
- **Access:** HogQL SELECT or WITH, and reads of insights and error tracking

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:

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

```sql
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

```text
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

```text
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

```text
-- 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.