Skip to main content

PostHog Integration

Connect PostHog to let agents query your product analytics during investigations. Agents run the PostHog CLI (posthog-cli api) in the sandbox to run HogQL/SQL over your events, persons, and sessions. They also read session replays, error-tracking issues, feature flags, and deploy annotations. This lets them correlate user impact and releases with an incident.

You can connect in one of two ways:

  • OAuth (recommended) — authorize Autoheal with a few clicks. There is nothing to create or rotate. The region (US/EU) is detected automatically. PostHog Cloud only.
  • Personal API key — paste a read-only key. This method works for PostHog Cloud and self-hosted. Use it if you self-host.

Capabilities​

Once connected, agents can:

CapabilityHow
Query data (HogQL/SQL)posthog-cli api call execute-sql over events, persons, sessions, and $exception events. This is the primary way to correlate errors, sessions, and metrics with a release/time window
Session replayList recordings and read metadata / replay links. Pivot from an error's $session_id straight to the replay
Error trackingRead error-tracking issues, exception events, and stack traces
Feature flagsRead feature flags and their state (flag flips are a common incident cause)
AnnotationsRead deploy/incident markers to align an incident with a release
Insights & dashboardsRead saved insights and dashboards
1
Open the integration

Go to Integrations in Autoheal, click PostHog, and keep the default OAuth method selected.

2
Authorize

Click Connect with PostHog. You'll be redirected to PostHog to approve read-only access. Approve, and you'll be sent back to Autoheal with the integration connected.

3
Done

Autoheal stores the OAuth token (encrypted) and auto-refreshes it. There's nothing to rotate. Autoheal detects the region of your PostHog account (US or EU) automatically.

note

OAuth requests read-only access across all PostHog resource types (every :read scope, plus identity), so investigations can read whatever they need. It never requests a write scope. You review and approve the grant on PostHog's consent screen, where you can also narrow it if you prefer.

Connect with a Personal API Key​

1
Create a read-only key

In PostHog, go to Settings → Personal API keys and create a key with read-only scopes. The simplest safe choice is the "Read-only access" preset (all :read, no writes). If you prefer least-privilege, use the "MCP Server" preset (query, session_recording, error_tracking, insight, dashboard, feature_flag) and additionally enable user:read and annotation:read. See Required Permissions for the full list. Restrict the key to the project(s) agents should read.

warning

user:read is required. The PostHog CLI resolves the current user before every call and fails without it. The "MCP Server" preset does not include it, so add it explicitly (or use "Read-only access").

2
Add it in Autoheal

In Integrations → PostHog, switch the method to Personal API Key, then enter:

  • Personal API Key — the phx_... key
  • Host — us.posthog.com, eu.posthog.com, or your self-hosted domain (no scheme)
  • Default Project ID — optional. Set it for single-project setups
3
Save

Enter a name (e.g., "PostHog Production") and click Save.

warning

PostHog US and EU are separate data planes. A personal API key is region-bound. It only works on the region it was created in. Make sure Host matches that region. Do not use an ingestion host (us.i.posthog.com / eu.i.posthog.com). Reads use the app host. (OAuth avoids this, because Autoheal detects the region for you.)

Correlating with deploys​

PostHog does not enforce a single way to tag releases, so tell Autoheal how you do it with an integration guide skill. Agents can correlate incidents to deploys using any of:

  • Annotations — deploy markers pinned to a timestamp
  • Error-tracking Releases — created by posthog-cli sourcemap upload with git metadata (commit-level linkage)
  • Event properties — a version property (commonly $app_version, but often a custom name) and an environment property or PostHog's Environments feature
tip

There is no guaranteed property name for version/environment. Capture yours in an integration guide skill, so agents filter on the right property instead of guessing. If you don't tag a version at all, agents correlate errors to deploys by time window + stack trace + the linked session replay.

Example Queries​

Once connected, you can ask an agent questions like:

Did errors spike in production after the last deploy? Break exceptions down by release.
Show session replays for users who hit the checkout error in the last hour.
Which feature flags changed in the 24h before this incident?
What deploy annotations are near this incident window?

Required Permissions​

Read-only access only. With OAuth, Autoheal requests these read scopes automatically. With a personal API key, create it with only these :read scopes:

ScopeWhy It's Needed
user:readRequired. The PostHog CLI resolves the current user (/api/users/@me/) before every call and aborts without it. Not part of the "MCP Server" preset, so enable it explicitly.
query:readRun HogQL/SQL queries (the primary read path)
session_recording:readList and read session recordings
error_tracking:readRead error-tracking issues and exceptions
feature_flag:readRead feature flags and their state
insight:read / dashboard:readRead saved insights and dashboards
annotation:readRead deploy/incident annotations
warning

PostHog API rate limits are applied org-wide across all keys. For the API-key method, provision a dedicated key (ideally under a bot user) so Autoheal's reads don't compete with your team's dashboards.

Troubleshooting​

The 'Connect with PostHog' button isn't shown

OAuth isn't enabled on your Autoheal instance. Use the Personal API Key method instead (it offers the same capabilities), or ask your Autoheal administrator to enable PostHog OAuth.

401 / Authentication failed (API key)
  • Check that the personal API key is correct and not revoked.
  • Check that Host matches the region the key was created in. A US key does not work on eu.posthog.com and vice versa.
403 / Missing scope
  • The key (or OAuth grant) is missing a required :read scope, or is restricted to a different project. The most common cause is a missing user:read (the "MCP Server" preset omits it). Re-create the key with access to the target project. Give it the scopes above, or use the "Read-only access" preset. For OAuth, reconnect so the new grant includes user:read.
Empty results
  • Check that you're querying the right project ID.
  • If you filter by version/environment, confirm the property name. PostHog enforces no standard, so the property may not be $app_version.
  • Check that the data exists for the time window (events may be sampled or retained for a limited period).
429 / Rate limited
  • PostHog rate limits are org-wide. Prefer fewer, bounded HogQL queries over many small calls, and use a dedicated key.

Additional Resources​