All docs
Connect

PostHog: connect PostHog Cloud with OAuth and work with analytics, flags and experiments

TL;DR

PostHog connects with OAuth through the PostHog Cloud region your organization lives in. Each project the sign-in reaches becomes its own connection. 29 reads and 20 writes; person data is masked in every answer, and launches, rollouts and deletes always wait for a person.

Connect step by step

  1. 1Open Integrations → PostHog, choose US (us.posthog.com) or EU (eu.posthog.com) and press Connect.
  2. 2Sign in to PostHog and approve the permissions below.
  3. 3Agent Planners saves one connection per project the sign-in reaches, grouped by region and PostHog organization. Each call is bound to its project.
  4. 4Press Refresh accounts to pick up projects created later.
Self-hosted PostHog cannot be connected — only the two PostHog Cloud regions. Re-authorize updates the same connections in place; Disconnect deletes the stored tokens (encrypted).

Permissions requested

PermissionWhy
openidthe sign-in's identifier (userinfo sub), so two people connecting the same project are two sign-ins
emailthe sign-in's email shown on the card and the team view
user:readlists every organization and project the person can reach (GET /api/users/@me/), used by the connect and Refresh accounts
project:readproject names, time zones and the project list (list_projects, account health)
query:readHogQL and every analysis query (run_query, trends, funnel, retention, paths, lifecycle, stickiness, session analysis, survey response counts)
insight:writeread, create and update saved insights (covers insight:read)
dashboard:writeread, create and update dashboards and add insight tiles (covers dashboard:read)
feature_flag:writeread flags; create INACTIVE flags; change a flag (a rollout or activation waits for a person); surveys with targeting need it too
experiment:writeread experiments; create drafts; launch / stop (a person approves)
survey:writeread surveys; create drafts; launch / stop (a person approves)
cohort:writeread, create and update dynamic cohorts
error_tracking:writeread error issues; resolve / suppress / reopen and assign them
session_recording:readrecording metadata only (duration, start, counts — never the replay, never who)
heatmap:readclick / scroll heatmap aggregates by URL
event_definition:readthe event names a query can use (list_event_definitions)
Not requested: profile; insight:read / dashboard:read / feature_flag:read / experiment:read / survey:read / cohort:read / error_tracking:read; query:write; session_recording:write; heatmap:write; person:read / person:write; project:write / organization:* / organization_member:*; batch_export:* / hog_function:* / webhook:* / integration:*; billing:* / data_deletion:*. PostHog's write permissions include read, so a :write permission is asked for instead of its :read twin.

What works

  • Analytics: read-only HogQL, trends, funnels, retention, paths, lifecycle, stickiness, session analysis and heatmaps. Windows are days or dates in the project's time zone; the answer says which window it used.
  • Saved work and product: insights, dashboards, feature flags, experiments (with results when PostHog has them), surveys (response counts only), cohorts (never members), error-tracking issues, event definitions, recording metadata.
  • Changes that follow your approval setting: insights, dashboards, dynamic cohorts, draft experiments and surveys, inactive feature flags, flag names and tags, error-issue status and assignee.
  • Always a person: turning a flag on or off, a rollout / condition / variant change, launching or stopping an experiment or survey, deletes.
  • Refused: persons, deleting recordings, members, billing, API keys, settings, batch exports, destinations and webhooks; static cohorts (uploaded lists of people).

Masking

  • Emails, names and person properties are removed from every answer.
  • Reading people (person properties, the persons table, email / name / IP properties) is refused over MCP and on automated runs.
  • Session recordings come back as metadata, with who it was replaced by "Person N"; the replay is never fetched.

Troubleshooting

  • A project is missing. The sign-in cannot reach it, or it is in the other region — connect again choosing that region.
  • 403 on a call. The resource is outside the permissions PostHog granted; Re-authorize and approve all of them.
  • Not yet tested on a live PostHog account. The integration was tested against simulated PostHog answers; tell us if PostHog answers differently.

Frequently asked questions

US or EU?
The region your PostHog organization was created in — the host you log in to (us.posthog.com or eu.posthog.com). Projects in both regions can be connected; each sign-in is for one region.
Can the agent read my users' emails?
No. Person data is masked in every answer, and person reads are refused over MCP and on automated runs.

About this platform

Related