Skip to main content

PostHog

Query PostHog events, insights, feature flags and experiments from agent work.

Connect it with: Sign in (OAuth), API key, MCP. PostHog's own documentation: https://posthog.com/docs/api/personal-api-keys.

What agents can do​

Connect PostHog so the agents working your tasks can reach it. With it connected, they can:

  • Through PostHog's MCP server, once the secret is linked to a project, use PostHog's ready-made tools for insights, flags and errors.
  • Run a HogQL query or read a saved insight to check a metric a task asks about.
  • Look up a feature flag's rollout and conditions before or after a release.
  • Read an experiment's results to report on a change.
  • Find the events and persons behind a bug report.
  • Create or update a feature flag or annotation, if the key has write scopes.

Before you start​

  • A PostHog account in the organization and projects agents should reach.
  • Know your PostHog host: US Cloud, EU Cloud or your own self-hosted address.
  • A Jaah account. Anyone can add a personal secret; an organization secret needs an Org Owner or Admin.

Connect with PostHog​

This is the quickest way in: you sign in to PostHog and approve what Jaah asks for. You never copy a key.

  1. In Jaah, open Secrets and select New.
  2. Search for PostHog and select its card.
  3. Give the secret a name you will recognize, such as the account or workspace it reaches, and choose who can use it (see Who can use it).
  4. Select Connect PostHog. PostHog's sign-in window opens.
  5. Sign in to PostHog if asked, check the access listed, and approve it.
  6. You land back in Jaah on the new secret, which reads Connected once its test passes.

If the button reads Jaah app not configured, this Jaah has no app registered at PostHog yet. Use an API key, or your own OAuth app, until it does.

Scopes Jaah requests​

Jaah asks PostHog for these scopes, and no others. A scope marked optional is a checkbox on the Connect screen: untick it and agents simply cannot do that part.

ScopeWhy Jaah asks for itRequired
user:readKnow who signed in, for Test and the secret's nameYes
project:readList the projects agents may queryYes
query:readRun HogQL queriesYes
insight:readRead saved insights and dashboards' insightsYes
feature_flag:readRead feature flags and their rolloutYes
experiment:readRead experiments and their resultsYes
person:readLook up persons behind eventsYes

Connect with an API key​

Prefer this when you cannot sign in with PostHog — for example a service account, or a token your admin issued. On the Connect screen select Use an API key instead.

Find each value first:

  • PostHog host: https://us.posthog.com for PostHog Cloud US, https://eu.posthog.com for PostHog Cloud EU (the address you sign in at), or your self-hosted PostHog's address. Not the us.i.posthog.com ingestion host.
  • Personal API key: PostHog > your avatar > Account settings > Personal API keys > Create personal API key: name it Jaah, pick the organizations or projects it may reach, choose scopes (at least User read, plus read on the data agents use, such as Query, Insight and Feature flag), then copy the key - PostHog shows it once.

Then add it to Jaah:

  1. In Jaah, open Secrets, select New, and pick the PostHog card.
  2. Name the secret and choose who can use it.
  3. Select Use an API key instead.
  4. Fill in PostHog host, Personal API key.
  5. Select Save. Jaah tests the secret straight away (see Test the connection).

Jaah encrypts what you type and never shows it again — not to you, and not to an admin.

Use your own OAuth app​

Not used: Connect PostHog always runs on this Jaah's own client, so there is no app of your own to create.

Test the connection​

Select Test on the secret. Jaah calls PostHog's API once (GET <PostHog host>/api/users/@me/) with the stored values, and shows who it answered as, or which value PostHog refused and the status it answered. Jaah also tests automatically when you save or reconnect.

The last result and its time stay on the secret's page, so you can see whether it still works without testing again.

Who can use it​

Every secret has an owner, and the owner decides who can use it:

  • Personal — only your own tasks can use it. This is the default.
  • Organization — every task in the organization can use it. Only Org Owners and Admins can choose this.
  • Attached to a project — every task on that project can use it, whoever started the task. See Attach a secret to a project.

More on owners and access: How secrets work.

Use it in an agent session​

An agent asks for the secret with its credential_get tool, by the secret's path, when it needs it, and gets the values for that one call. The path is the owner's prefix and the secret's name:

  • org/<name> for an organization secret,
  • projects/<project>/<name> for one attached to a project,
  • me/<name> for your personal one.

A signed-in connection hands the agent a live access_token, with access_token_expires_at. Jaah refreshes it before it expires, so an agent never handles a refresh token.

A key connection hands the agent its fields: base_url, api_key.

Tell the agent in your task description which secret to use, for example “use the PostHog secret org/posthog”.

PostHog also runs an MCP server, which gives agents ready-made PostHog tools instead of raw API calls. A project's agents get those tools only once you link the secret to the project:

  1. Open the project and its MCP tab.
  2. Select Link, pick the PostHog secret, and confirm.
  3. New tasks on the project start with the PostHog tools. Tasks already running keep the tools they started with.

Jaah connects agents to the server through a local bridge, so the token never appears in the agent's configuration or its transcript. A Google Antigravity session in the terminal runtime runs without these tools; on ACP it gets them.

Manage, rotate or disconnect​

Everything is on the secret's page under Secrets:

  • Rotate a key: create a new key at the vendor first, then select Replace on the secret and paste it. Revoke the old key at PostHog once the test passes. Steps: Replace or delete a secret.
  • Reconnect: when PostHog ends the grant (a password change, a revoked app, an expired refresh), the secret shows Needs reconnect. Select Reconnect and sign in again; agents get the new token on their next call.
  • Disconnect: select Delete. The stored values are destroyed and agents lose access on their next call. To end access at PostHog's side too, revoke Jaah in PostHog's settings, or revoke or delete the key at PostHog.

Limitations​

  • Connect reads only (queries, insights, flags, experiments, persons); a personal API key with write scopes is needed to change a flag or add an annotation.
  • Connect reaches PostHog Cloud (US or EU, found after sign-in); a self-hosted PostHog needs a personal API key.
  • Both act as the person who signed in or created the key, within the scopes and projects chosen for it.
  • PostHog limits each user to 10 personal API keys.
  • PostHog rate-limits private API calls (for example, analytics queries are capped per minute); heavy query loops are throttled.
  • The project API key (phc_) only sends events and cannot read data, so it does not work here.
  • Agents can do only what the connected PostHog account and its granted scopes allow.

Troubleshooting​

Test says PostHog rejected the personal API key (401)

The key was deleted, mistyped or is the project key (phc_) rather than a personal key (phx_). Create a personal key in Account settings and select Replace.

Test says PostHog rejected the key (403)

The key lacks the User read scope Jaah's test uses. Edit the key's scopes in Account settings > Personal API keys.

Test cannot reach PostHog or the key is rejected though it is correct

The host does not match where the account lives: an EU account needs https://eu.posthog.com. Fix PostHog host.

Connect ends with no organisation or site for this sign-in

PostHog's US and EU clouds both refused the new token. Select Connect again and sign in to the account agents should use.

Agents get 403 on one project

The key was limited to other projects. Add the project to the key's access, or create a key for it.

Still stuck? Select Test and read the result: it names the value PostHog refused and the status it answered.

FAQ​

Is there a Sign in with PostHog button?

Yes: Connect PostHog. PostHog needs no app registered for it, so it works on every Jaah.

Which scopes should the key have?

Read scopes for what agents should look at (Query, Insight, Feature flag, Experiment, Person) plus User read for the test. Add write scopes only for changes you want agents to make.

Can Jaah or an admin see the key or token?

No. Jaah stores it encrypted and never shows it again. Only the tasks allowed to use the secret receive it, at the moment they ask for it.

Can I connect more than one PostHog account?

Yes. Add one secret per account, each with its own name, and tell the agent which one to use.