Menu

Mattering Automations PostHog integration

Connect PostHog to Mattering Automations: HogQL queries over events, insights, dashboards, persons, cohorts, feature flags, annotations, session recording metadata, and schema discovery as workflow steps, authenticated with a PostHog personal API key.

The Mattering Automations PostHog integration adds PostHog to your automation canvas: run HogQL (SQL) queries over your events, persons, and sessions, create and update insights and dashboards, read persons and build cohorts, manage feature flags including the production toggle, read experiments, drop deploy-marker annotations, triage session recordings by their metadata, and discover a project's event and property schema.

Setup takes a few minutes: create a personal API key in PostHog's account settings, attach it as a credential in Mattering, and test the connection. This guide walks through each step and ends with the full node reference.

The behavior boundary is worth knowing up front. HogQL is SELECT-only, so PostHog: Run HogQL Query reads data and cannot change it. The feature flag nodes can change production behavior: PostHog: Create Feature Flag defaults new flags to inactive on purpose, PostHog: Update Feature Flag is the toggle that changes what real users experience immediately, and PostHog: Delete Feature Flag (Soft) is a reversible soft delete. Exactly one node is destructive: PostHog: Delete Person, the GDPR erasure operation. Verify the integration with read nodes only.

Before you start

  • A PostHog account with at least one project, on US Cloud, EU Cloud, or a self-hosted instance.
  • Permission to create a personal API key in your PostHog account settings, with the scopes your automations need.
  • A Mattering workspace with access to the Automations app.
  • For EU Cloud or self-hosted: the API host your organization lives on (eu.posthog.com, or your own domain), which you will set in each node's host field.

Create a PostHog personal API key

Mattering authenticates to PostHog with a personal API key (the phx_ prefix), sent as a Bearer credential on every request. The key acts as the user who created it and carries per-resource scopes chosen at creation. This is a different credential from the phc_ project key your website snippet uses for event ingestion; the two are not interchangeable, and this integration uses only the personal key.

In PostHog, open your account settings and go to Personal API Keys.
Create a key, select the scopes your automations need (each node's description in Mattering names its required scope, for example query:read or feature_flag:write), and choose which organization or projects the key may access.
Copy the key immediately.
PostHog shows a personal API key exactly once, at creation; afterwards only a masked form is visible and the value cannot be retrieved. Scopes are also fixed at creation: a key missing a scope returns 403 on the nodes that need it even though the credential itself is valid, and the fix is a new key, not an edit.

Connect PostHog to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose PostHog from the list.
Click Create new credential, paste your personal API key, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection: Mattering calls PostHog's current user endpoint on the US Cloud host and confirms the key authenticates. If your organization is on EU Cloud, this test fails even with a valid key; see troubleshooting below, and verify with a node instead.
Click Connect. All 33 PostHog nodes appear in your canvas palette.

Verify it works

After connecting, open any automation canvas and check the palette: a PostHog section should list the query and action nodes. Drop PostHog: Get Current User onto the canvas and run a test step. It takes no parameters and is a safe, read-only call; a successful response returns the account behind the key plus its current organization and project, and the team.id value is the numeric project id that every project-scoped node needs. On EU Cloud or self-hosted, set the node's host field first; a passing run here proves the credential works regardless of what Test Connection said.

To confirm the analytics surface, run PostHog: Run HogQL Query with a simple statement such as SELECT count() FROM events WHERE timestamp > now() - INTERVAL 7 DAY. HogQL is SELECT-only, so nothing in the verify path can change data, and everything here stays far away from the flag toggles and PostHog: Delete Person.

Node reference

33 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 23

PostHog: Get Cohort

posthog_get_cohort

Retrieve one cohort by numeric id, including its filter definition, member count, and calculation status. Requires the cohort:read scope.

PostHog: Get Current User

posthog_get_current_user

Return the account behind the personal API key: name, email, and the current organization and project context (organization.id and team.id feed every other PostHog node). Zero required parameters, so it doubles as the credential health check. The personal API key is never echoed back.

PostHog: Get Dashboard

posthog_get_dashboard

Retrieve one dashboard by numeric id, including its tiles and the insights on it. Requires the dashboard:read scope.

PostHog: Get Experiment

posthog_get_experiment

Retrieve one experiment by numeric id: its feature flag, variants, timing, and configuration. Requires the experiment:read scope.

PostHog: Get Feature Flag

posthog_get_feature_flag

Retrieve one feature flag by numeric id: key, active state, full rollout filters, and linked experiments. Requires the feature_flag:read scope.

PostHog: Get Insight

posthog_get_insight

Retrieve one insight by numeric id, including its full query definition and latest cached result. Requires the insight:read scope.

PostHog: Get Organization

posthog_get_organization

Retrieve one organization by UUID: name, membership level, and its teams/projects summary. Requires the organization:read scope.

PostHog: Get Person

posthog_get_person

Retrieve one person by id: all their distinct_ids and person properties. Person records carry personal data that persists in execution records. Requires the person:read scope.

PostHog: Get Project

posthog_get_project

Retrieve one project by its numeric id: name, timezone, and the phc_ project api_token (the client-side ingestion token, public by design). Requires the project:read scope.

PostHog: Get Session Recording

posthog_get_session_recording

Retrieve one session recording's METADATA by id (duration, activity counts, person). The raw replay data itself is not served by this API. Requires the session_recording:read scope.

PostHog: List Annotations

posthog_list_annotations

List a project's annotations (the markers that appear on insight charts, for example deploy notes). Requires the annotation:read scope. Response is {count, next, previous, results}: page with limit and offset until next is null.

PostHog: List Cohorts

posthog_list_cohorts

List a project's cohorts with ids, names, member counts, and whether each is static or dynamic. Requires the cohort:read scope. Response is {count, next, previous, results}: page with limit and offset until next is null.

PostHog: List Dashboards

posthog_list_dashboards

List a project's dashboards with ids, names, and pinned state. The id feeds the insight nodes' dashboards field. Requires the dashboard:read scope. Response is {count, next, previous, results}: page with limit and offset until next is null.

PostHog: List Event Definitions

posthog_list_event_definitions

List the event names a project has ever seen (schema discovery): the vocabulary available to HogQL queries, insights, and cohort filters, with last_seen_at per event. Requires the event_definition:read scope. Response is {count, next, previous, results}: page with limit and offset until next is null.

PostHog: List Experiments

posthog_list_experiments

List a project's A/B experiments with ids, names, linked feature flags, and start/end dates. Requires the experiment:read scope. Response is {count, next, previous, results}: page with limit and offset until next is null.

PostHog: List Feature Flags

posthog_list_feature_flags

List a project's feature flags with ids, keys, active state, and rollout filters. Requires the feature_flag:read scope. Response is {count, next, previous, results}: page with limit and offset until next is null.

PostHog: List Insights

posthog_list_insights

List a project's saved insights (trends, funnels, and the rest) with their ids, short_ids, names, and dashboard links. Requires the insight:read scope. Response is {count, next, previous, results}: page with limit and offset until next is null.

PostHog: List Organizations

posthog_list_organizations

List the organizations the personal API key can see, with their UUIDs and member counts. The organization id feeds PostHog: List Projects. Requires the organization:read scope. Response is {count, next, previous, results}: page with limit and offset until next is null.

PostHog: List Persons

posthog_list_persons

List a project's persons, filterable by distinct_id, email, free-text search, or property filters. Person records carry personal data (emails, names) that persists in execution records; fetch only what the automation needs. Requires the person:read scope. Response is {count, next, previous, results}: page with limit and offset until next is null.

PostHog: List Projects

posthog_list_projects

List the projects in an organization. Each result's numeric id field is the project_id every project-scoped PostHog node needs. Results also include api_token, the phc_ client-side project token (public by design, but it does persist in execution records). Requires the project:read scope. Response is {count, next, previous, results}: page with limit and offset until next is null.

PostHog: List Property Definitions

posthog_list_property_definitions

List the event or person property names a project has seen (schema discovery), with each property's data type. Pairs with List Event Definitions to let an agent learn a project's analytics schema before writing HogQL. Requires the property_definition:read scope. Response is {count, next, previous, results}: page with limit and offset until next is null.

PostHog: List Session Recordings

posthog_list_session_recordings

List session replay METADATA: who, when, duration, and activity counts. The raw replay video/snapshot data is not available through this API (export it from the PostHog UI); this node is for finding and triaging sessions, for example alerting on long rage-click sessions. Requires the session_recording:read scope. Response is {count, next, previous, results}: page with limit and offset until next is null.

PostHog: Run HogQL Query

posthog_query

Run a HogQL query (PostHog's SQL dialect) against a project's events, persons, and sessions: the current workhorse for pulling analytics data into an automation. Write the SQL in the hogql field; HogQL is SELECT-only, so this node reads data and cannot mutate it. Results come back as data.results (array of rows) with data.columns. Default 100 rows, LIMIT up to 50000; rate limit 2400 queries/hour per organization. Requires the query:read scope.

Action nodes 10

PostHog: Create Annotation

posthog_create_annotation

Create an annotation, the classic deploy marker: drop 'Deployed v2.4.0' at a timestamp and it appears on every insight chart, correlating releases with metric changes. Reversible: delete the annotation in PostHog to undo. Requires the annotation:write scope.

PostHog: Create Cohort

posthog_create_cohort

Create a cohort. With is_static true you get a static (manually curated) cohort, populated afterwards in the PostHog UI or via CSV; with is_static false, provide filters so membership is computed dynamically. Reversible: delete the cohort in PostHog to undo. Requires the cohort:write scope.

PostHog: Create Dashboard

posthog_create_dashboard

Create a dashboard, empty or from a PostHog template. Add insights to it afterwards with PostHog: Update Insight (its dashboards field). Reversible: soft-delete via the update node. Requires the dashboard:write scope.

PostHog: Create Feature Flag

posthog_create_feature_flag

Create a feature flag. CAUTION: if your application code already checks this flag key, creating it active changes real production behavior immediately. Reversible (toggle active off or soft-delete), but treat it like a deploy. Requires the feature_flag:write scope.

PostHog: Create Insight

posthog_create_insight

Create a saved insight from a query definition, optionally pinning it onto dashboards at creation. Reversible: update the insight with deleted true (or delete it in the UI) to remove it. Requires the insight:write scope.

PostHog: Delete Feature Flag (Soft)

posthog_delete_feature_flag

Soft-delete a feature flag by setting deleted true, which is the only deletion PostHog's API allows (hard DELETE is rejected; the docs mandate this PATCH instead). A soft-deleted flag STOPS EVALUATING, so if it was active this changes production behavior immediately. Reversible: PATCH deleted false (via PostHog: Update Feature Flag's extra_body) restores it. Requires the feature_flag:write scope.

PostHog: Delete Person

posthog_delete_person

DESTRUCTIVE: permanently delete a person from the project, with no undo. With delete_events true, all of the person's historical events are also queued for permanent, asynchronous deletion (processed off-peak). This is the GDPR right-to-erasure operation; deletion is not instant but it is irreversible once queued. Requires the person:write scope.

PostHog: Update Dashboard

posthog_update_dashboard

Update a dashboard's name, description, pinned state, or tags. Setting deleted true soft-deletes it (deleted false restores). Only fields you fill are changed. Requires the dashboard:write scope.

PostHog: Update Feature Flag

posthog_update_feature_flag

Update a feature flag: the active field is the kill switch and rollout toggle. CAUTION: toggling active or changing filters changes what real users experience in production IMMEDIATELY. Reversible (set it back), but gate this node carefully in automations. Only fields you fill are changed. Requires the feature_flag:write scope.

PostHog: Update Insight

posthog_update_insight

Update an insight: rename it, replace its query, or set dashboards to add it to (or remove it from) dashboards, which is how an insight lands on a dashboard via the API. Setting deleted true soft-deletes it (deleted false restores). Only fields you fill are changed. Requires the insight:write scope.

Using the integration

On the automation canvas

PostHog nodes chain with every other node: a scheduled set of PostHog: Run HogQL Query steps can become a weekly metrics digest delivered as a report task in Mattering Productivity, query rows can append to a Mattering database for trend history, and a feature flag rollout can wait behind an approval task so PostHog: Update Feature Flag only runs after a person signs off.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools. Claude, ChatGPT, and Matter can use PostHog: List Event Definitions and PostHog: List Property Definitions to learn a project's analytics vocabulary, then answer real product questions by writing SQL for the HogQL node. The schema reads and the SELECT-only query node are the safest PostHog surface to hand an agent.

HogQL as the front door to events

PostHog: Run HogQL Query is the workhorse: write SQL in the hogql field and the runner wraps it into PostHog's query envelope for you. It supersedes the older events list APIs, which is why this integration ships one query node rather than several half-covered event readers. Know its limits: results default to 100 rows with LIMIT accepted up to 50000, personal API keys cannot use OFFSET pagination (paginate on a timestamp column instead), and queries are rate limited to 2400 per hour per organization.

Feature flags: create dark, enable deliberately

PostHog: Create Feature Flag defaults active to false, so a new flag changes nothing until something turns it on, unless your application code already checks that key. PostHog: Update Feature Flag is the deliberate step: its active field is the rollout toggle and kill switch, and flipping it changes what real users experience immediately. PostHog: Delete Feature Flag (Soft) is the only deletion PostHog's API allows, a PATCH setting deleted to true; a soft-deleted active flag stops evaluating, and restoring deleted to false brings it back. Gate the toggle and the soft delete the way you would gate a deploy.

Regions and self-hosted instances

PostHog Cloud is region sharded: US organizations live on us.posthog.com and EU organizations on eu.posthog.com, with no crossover. Every node carries a host field defaulting to us.posthog.com; EU customers set eu.posthog.com, and self-hosted instances use their own domain since they expose the same API surface. The one asymmetry is the connector-level Test Connection, which calls the US host only; EU and self-hosted credentials verify through a node run instead.

Scopes and personal data

Each node's description names the scope it requires, such as insight:read or person:write, and a key missing that scope gets a 403 on that node with an otherwise valid credential. Two data notes: person and session recording responses carry personal data (emails, names) that persists in execution records, so fetch only what the automation needs; and PostHog: List Session Recordings and PostHog: Get Session Recording return metadata only, since the raw replay data is not served by this API.

Troubleshooting

Test Connection fails with a 401
The key is invalid or picked up stray whitespace when pasted. PostHog shows a personal API key only once at creation and never again, so if the pasted value is wrong there is nothing to re-copy: create a fresh key in account settings and update the credential on the connector.
Test Connection fails but the key is valid (EU Cloud or self-hosted)
Known gap, stated plainly: the connection test calls PostHog's current user endpoint on the US Cloud host, so a key whose organization lives on EU Cloud or a self-hosted instance fails the test even though it is perfectly valid. The nodes themselves work once each node's host field is set (eu.posthog.com, or your own domain). Verify by running PostHog: Get Current User with the host field set instead of relying on Test Connection.
A node returns a 403 even though Test Connection passed
The key is missing a scope. Personal API keys carry per-resource scopes fixed at creation, and the connection test only exercises the current user endpoint, so a key can pass it while lacking, say, feature_flag:write. The failing node's description names the scope it requires. Scopes cannot be edited afterwards: create a new key with the right scopes and update the credential.
PostHog: Run HogQL Query is rejected when paginating with OFFSET
Personal API keys cannot use OFFSET in HogQL queries; that is a PostHog restriction, not a connector one. Paginate by keyset instead: order by a timestamp column and filter each page on values greater than the last row seen. Also remember the LIMIT ceiling: results default to 100 rows and an explicit LIMIT is accepted up to 50000.
Queries start failing with rate limit errors
The query endpoint allows 2400 queries per hour per organization, counted across all members and all tooling, not just Mattering. Other private API calls have their own budgets (analytics reads 240 per minute and 1200 per hour, writes 480 per minute and 4800 per hour). Space scheduled HogQL sweeps out, combine related metrics into fewer SELECTs, and let retries back off rather than hammering.
A project-scoped node returns a 404 for a project that definitely exists
The project_id field takes the numeric project id, not the phc_ token and not a UUID. Get it from the id field of PostHog: List Projects or from team.id in PostHog: Get Current User. Also confirm the node's host field matches the region the organization lives on; a US host with an EU project id finds nothing.
A feature flag was deleted and production behavior changed
That is how PostHog's flag deletion works: PostHog: Delete Feature Flag (Soft) sets deleted to true (the only deletion the API allows), and a soft-deleted flag stops evaluating, so if the flag was active, deleting it behaves like switching it off for everyone. It is reversible: restore the flag by setting deleted back to false through PostHog: Update Feature Flag's extra body, and it resumes evaluating with its previous configuration.
PostHog: Delete Person ran but the person or their events still appear
Person deletion is asynchronous by design. The person record is removed and, with delete_events enabled, their historical events are queued for permanent deletion processed off-peak, so events can remain visible for a while after the node succeeds. Do not re-run the node to hurry it along. Deletion is not instant, but it is irreversible once queued: this is the GDPR erasure path and the one destructive node in the integration, so gate it behind an approval.

PostHog is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products