PostHog connector setup

Operator·5 minutes to read

This connector reads PostHog with a personal API key, not with the "bring your own OAuth app" shape most pages beside this one describe, so there is no botseon oauth-app set step for it (see docs/connectors/README.md). The key is what this connector's calls carry as a bearer token.

1. Create the key in PostHog

Any member of a PostHog organization can create their own key; no admin approval is needed.

Sign in to PostHog at your region's address — https://eu.posthog.com or https://us.posthog.com.
Open your account settings (not the project's) and go to Personal API keys, then Create a personal API key. Give it a label you will recognise, such as "Botseon".
Grant it only the scopes this connector's tools need (F-PLUG-1), never the full-access *:
- query:read — read recent events and run HogQL queries through the Query endpoint.
- insight:read — list saved insights and read one.
- dashboard:read — list the project's dashboards.
- feature_flag:read — list the project's feature flags and read one.
- person:read — list the people the project has recorded.
- experiment:read — list the project's experiments.
- error_tracking:read — list the project's error tracking issues.
- annotation:read — list the project's annotations.
- annotation:write and feature_flag:write — only if bots may add annotations and create or change feature flags. Leave them out for a read-only key; the member then ticks only the reads, and no write tool is offered.
Copy the key now. PostHog shows it once and never again.

The Project API key on the project's own settings page is the wrong key: it sends events into PostHog and cannot read anything back out.

2. The region and the project

Two per-installation plugin variables (PLUGIN_VARIABLES.posthog, both kind: string):

PostHog region (region) — eu or us. PostHog Cloud EU and US are separate instances, the region was chosen when the organization signed up, and it cannot be changed later. If you are unsure, it is the address you sign in at. A key read against the wrong region fails with an authorisation error, so check this first when a connection is refused.
PostHog project id (project_id) — the number in the project's address and on its settings page, for example 12345.

The driver maps region through a fixed two-entry table to https://eu.posthog.com or https://us.posthog.com; nothing a member types becomes part of a hostname.

3. What each tool does

Tool	Reads
`posthog.list_events`	The project's most recent events, newest first, optionally one event name and only after a time — through PostHog's Query endpoint.
`posthog.run_query`	A HogQL `SELECT` through the Query endpoint, which PostHog runs as a read: its columns and at most 500 rows.
`posthog.list_insights`	The project's saved insights, metadata only (nothing is computed): id, short id, name, description.
`posthog.get_insight`	One saved insight by its id or short id, with its latest result.
`posthog.list_dashboards`	The project's dashboards: name, description and whether each is pinned.
`posthog.list_feature_flags`	The project's feature flags, one page at a time: key, name, and whether each is active or archived.
`posthog.get_feature_flag`	One feature flag by its id, with each release condition's rollout and how many property conditions narrow it.
`posthog.list_persons`	The people the project has recorded, searchable by email, name or distinct id.
`posthog.list_experiments`	The project's experiments, optionally one status: name, flag key, status, start and end.
`posthog.list_error_issues`	The project's error tracking issues: name, status, severity and when each was first seen.
`posthog.list_annotations`	The project's annotations: text, time and scope.
`posthog.create_annotation`	Write, asks first: one annotation on the project's (or organization's) charts.
`posthog.create_feature_flag`	Write, asks first: a new flag with one release condition, off unless asked for on.
`posthog.update_feature_flag`	Write, asks first: switch a flag on or off, rename it, or change the rollout of its one release condition. Nothing deletes.

PostHog limits API use per project: the Query endpoint to 2,400 calls an hour, and other reads to 480 a minute. A member may notice a short pause when a busy project reaches one.

4. How a member connects it, and what this page cannot close

The catalogue row (packages/db/seed/catalogue.json) ships available: true (F-1199). A member adds PostHog, fills in PostHog region and PostHog project id in the plugin's settings, and pastes a personal API key on the account sheet, ticking the scopes they gave it. Its key row is posthog in API_KEY_CONNECTORS_BESIDE_CATALOGUE (packages/core/src/api-key-connectors.ts), with feature_flag:read required.

Before anything is stored, Botseon makes one read with the key — GET /api/projects/{project_id}/feature_flags/?limit=1 on the region's host — so a wrong region, a wrong project and a refused key are all reported on the sheet, and nothing is kept. An unset or malformed region or project id is named by its field before any request leaves.

The OAuth alternative is not built: PostHog's OAuth is real and needs no approval from PostHog (an app's client id is the address of a small document the app hosts on its own domain), but standing that document up is shared work this connector does not do.

Data stays in the region the organization chose: PostHog Cloud EU is a wholly separate instance in Frankfurt (AWS eu-central-1), and with region set to eu this connector calls only it.

Last verified against build 331481c.