> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meetsquad.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# PostHog

> Query your product analytics from an agent, and run one when PostHog forwards an event.

Qualitative feedback tells you what customers say. PostHog tells you what they do. Connecting it lets an [agent](/agents) run SQL against your product analytics mid-run, so a recommendation can cite behaviour as well as quotes.

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/squad/NVM9RUFBB2kdWosT/images/integrations-posthog-light.png?fit=max&auto=format&n=NVM9RUFBB2kdWosT&q=85&s=fbb2fcb4ff34d7d41794008a2b44da6c" alt="PostHog integration settings" width="2880" height="1800" data-path="images/integrations-posthog-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/squad/NVM9RUFBB2kdWosT/images/integrations-posthog-dark.png?fit=max&auto=format&n=NVM9RUFBB2kdWosT&q=85&s=f74d2426bf75f3b8c02e338574e8d8f6" alt="PostHog integration settings" width="2880" height="1800" data-path="images/integrations-posthog-dark.png" />
</Frame>

## Connect

PostHog uses an API key rather than a redirect.

<Steps>
  <Step title="Open the connect form" icon="chart-column">
    Click **Connect** on the PostHog card. A form opens.
  </Step>

  <Step title="Fill in the three fields" icon="key-round">
    * **Region.** US or EU, matching where your PostHog project lives.
    * **Project ID.** From PostHog under Settings, then Project.
    * **API key.** A personal API key, created in PostHog under Settings, then Personal API keys.
  </Step>

  <Step title="Submit" icon="check">
    Submit and the card turns green. One connection covers one PostHog project.
  </Step>
</Steps>

## What it brings in

<Note>
  Nothing from PostHog becomes a signal. It's a query surface for agents, not a source of customer voice.
</Note>

## Triggers

One trigger, **Event captured**. It fires when PostHog forwards an event to Squad from a webhook destination you set up on your side. PostHog's destination filters decide which events get forwarded, so you define what this trigger reacts to.

The PostHog detail page in Squad shows the webhook endpoint to paste into that destination, with a copy button.

<Warning>
  Filter tightly in PostHog. A destination pointed at a high-volume event will start an agent run every time it fires.
</Warning>

<Note>
  The destination also has to send the shared secret header Squad checks, `x-squidge-webhook-secret`. The app shows the URL but not the secret value, so ask support for it when you configure the destination.
</Note>

## Tools

<Tabs>
  <Tab title="Read">
    | Tool | What it does |
    | - | - |
    | **Run HogQL query** | Runs a SQL-style query against the connected project and returns the columns and rows, capped at the first 100 rows. |
    | **List insights** | Returns the saved insights (charts and dashboards) in the project, 25 by default and up to 100. |

    Run HogQL query does the real work. Events, trends, funnels and retention are all expressed as SQL.
  </Tab>

  <Tab title="Write">
    PostHog has none. Squad queries your analytics and never writes to them.
  </Tab>
</Tabs>

## A worked example

You have an insight claiming customers abandon onboarding at the workspace-invite step. Ask an agent with PostHog read tools to check it. It writes a HogQL query counting how many users reach each onboarding step over the last 30 days. The rows either confirm the drop-off or show the complaint is louder than the behaviour, and that answer goes into the [brief](/briefs) as a number rather than a hunch.

## Limits

Queries return the first 100 rows, so aggregate in the query rather than pulling raw events. One project per connection. The trigger fires for whatever your PostHog destination forwards, which makes filtering in PostHog the only volume control you have.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.