PostHog: what this connector can do

Member·9 minutes to read

What this page is for

docs/connectors/posthog.md is the setup guide for whoever runs your organisation's Botseon deployment. This page is the other half: what PostHog lets a bot do once it is connected to your PostHog project, what you create at PostHog to connect it, what it asks you for along the way, its limits and errors, and how to take the connection away again, in Botseon and at PostHog.

Read events, run HogQL queries, and read insights, dashboards, feature flags, experiments, people, error tracking issues and annotations for a project; add annotations and create or switch feature flags after you approve.

What you create at PostHog

You connect PostHog with your own personal API key — there is no sign-in screen and nothing for an administrator to approve. Any member of a PostHog organisation can make one.

Sign in to PostHog where you normally do — https://eu.posthog.com (EU) or https://us.posthog.com (US). That address is your region.
Open your account settings (your avatar, then settings — not the project's settings) and go to Personal API keys, then + Create a personal API Key. Label it Botseon so you can find it again.
Choose the scopes below, never "All access" (*), and limit the key to the one project you want a bot to use.
Copy the key straight away: PostHog shows it once.

The Project API key (sometimes called the project token) on the project's own settings page is the wrong key. It sends events into PostHog and cannot read anything back out.

Connecting it in Botseon

Open Plugins, find PostHog and press Add.
In the plugin's settings, fill in PostHog region (eu or us) and PostHog project id (the number in your project's address, for example 12345). The key is checked against both, so Botseon asks for them first.
Under Accounts, paste the key and tick the scopes you gave it at PostHog. feature_flag:read is required: it is what Botseon reads to check the key works.
Press Connect. Botseon makes one read at PostHog with the key — the project's feature flags, one row — and stores the key, encrypted, only if PostHog accepts it.

What a bot can do with it

Read — PostHog tells a bot things, nothing changes

Tool	What it does
`posthog.list_events`	List recent product events for a project, newest first, optionally one event name and only after a time.
`posthog.run_query`	Run a HogQL query against the project and return its columns and rows (at most 500).
`posthog.list_insights`	List the project's saved insights — names and descriptions, not their results.
`posthog.get_insight`	Read one saved insight and its latest result.
`posthog.list_dashboards`	List the project's dashboards.
`posthog.list_feature_flags`	List the project's feature flags: key, name, on or off, archived.
`posthog.get_feature_flag`	Read one feature flag with its release conditions and their rollout percentages.
`posthog.list_persons`	List the people the project has recorded, searchable by email, name or distinct id.
`posthog.list_experiments`	List the project's experiments, optionally by status (running, draft, …).
`posthog.list_error_issues`	List the project's error tracking issues with their status and severity.
`posthog.list_annotations`	List the project's annotations.

Write — PostHog lets a bot change things

Tool	What it does
`posthog.create_annotation`	Add an annotation — a note at a point in time — to the project's charts.
`posthog.create_feature_flag`	Create a feature flag with a key and a rollout percentage. It starts off unless you ask for it on.
`posthog.update_feature_flag`	Switch a flag on or off, rename it, or change the rollout of a flag that has one release condition.

No tool deletes anything at PostHog.

The permissions it asks for, in plain words

Every call a bot makes through this connector is tagged with what kind of thing it is. Only the tags below ever apply here — a tag this connector's tools never carry is not listed, because it can never ask you for it.

read — Looks something up. Nothing changes, and nothing is sent anywhere. A bot never has to ask first for this.
write — Changes something inside the connected account — creates, edits or files something. Asks you first, unless you have told Botseon to always allow that exact action.

The PostHog scopes, and what each one unlocks

PostHog names its permissions per resource. These are the ones to tick at PostHog and again in Botseon:

Scope	Lets a bot
`query:read`	list events and run HogQL queries
`insight:read`	list and read saved insights
`dashboard:read`	list dashboards
`feature_flag:read`	list and read feature flags — required, Botseon's key check uses it
`person:read`	list people
`experiment:read`	list experiments
`error_tracking:read`	list error tracking issues
`annotation:read`	list annotations
`annotation:write`	add annotations
`feature_flag:write`	create feature flags and switch or change them

The read tools are offered once every read scope is ticked; the write tools once both write scopes are. A key created read-only gets no write tool at all. If you tick a scope the key does not really carry, the first tool that needs it is shown as Disabled with PostHog's reason and the rest keep working; add the scope at PostHog, then press I updated the key on the account.

Limits

Only the tools above. Nothing outside that list is possible through this connector, however a bot is asked to use it. Each account reaches one region and one project — the two values in the plugin's settings — whatever else the key could reach.

A query returns at most 500 rows to the bot, and PostHog stops any query after 10 seconds.
PostHog's own limits: 2,400 query calls an hour for the project (240 a minute, three at once), 240 analytics reads a minute, 480 other reads and writes a minute. A busy project may see a short pause.
A rollout change is refused for a flag with more than one release condition — change those in PostHog, where you can see which condition you mean.

Errors you may see

What Botseon says	What it means	What to do
PostHog region is required — this plugin exposes no tools until it is filled in.	The key is checked against your region, and it is not set, or is not `eu` or `us`	Fill in the region in this plugin's settings, then connect
PostHog project id is required — this plugin exposes no tools until it is filled in.	The project id is not set, or is not the number PostHog shows	Fill in the project id in this plugin's settings, then connect
The provider refused that key. Check it was created with feature_flag:read and try again.	PostHog did not accept the key for that region and project	Check the region first (a key from the other region is unknown there), then the project id, then that the key has `feature_flag:read`
Disabled: …, beside one tool	The key lacks that tool's PostHog scope or this project	Add the scope at PostHog, then I updated the key
A bot reports PostHog is rate-limiting this key	One of the limits above	Wait a minute and ask again; Botseon waits as long as PostHog says to
A bot reports PostHog could not find that resource	No such insight, flag or project	Check the id

Disconnecting

In Botseon

Open Plugins from the sidebar, press this connector's card to open its detail page, and under Accounts press Disconnect to delete the stored key and keep the account, or the ✕ next to it (labelled "Remove account" and the account's name) to delete the account too — or Uninstall to remove the plugin and every account connected to it at once. Each one deletes the stored key immediately: no PostHog tool is offered for the account from that moment on. Install a plugin walks through the same screen step by step.

At PostHog

Removing the account in Botseon deletes the stored key from Botseon, but the key itself stays valid at PostHog until you revoke it there — Botseon has no way to revoke a key it did not issue. In your PostHog account settings, under Personal API keys (the same place you created it), delete the key, or open it and use Roll key, which invalidates the old value at once.

What Botseon keeps, and how your data is used

Whatever a bot reads or writes through this connector becomes part of your conversations and the record of that run — the same records, and the same retention schedule, as everything else a bot works on. Botseon is the processor for that content; your organisation decides what it may read and remember, and can delete it sooner than the schedule would on its own.

Your data is sent to a model provider only to produce the bot's answer, and for nothing else — it is not used to train any model. The Privacy Policy's Models and How long we keep it sections have the full detail, including exactly how long each kind of record is kept for.

With the region set to eu, this connector calls only PostHog Cloud EU (https://eu.posthog.com).