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.
Connect PostHog to Mattering
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
Test Connection fails but the key is valid (EU Cloud or self-hosted)
A node returns a 403 even though Test Connection passed
PostHog: Run HogQL Query is rejected when paginating with OFFSET
Queries start failing with rate limit errors
A project-scoped node returns a 404 for a project that definitely exists
A feature flag was deleted and production behavior changed
PostHog: Delete Person ran but the person or their events still appear
Related
The PostHog MCP
What connecting PostHog unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
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.