Query PostHog data and manage feature flags from Guild agents

Integrations · PostHog

A Guild agent can query your PostHog project, read analytics data, and manage feature flags without ever handling your API key. Guild stores the credential server-side and injects it through its credential proxy, so your key stays out of agent code, prompts, and state. Credential policies let you restrict which operations each agent can call, and every request is governed before it leaves Guild.

Book a demo

See how teams govern agents that use PostHog.

Start free

Connect PostHog and scope your first agent.

What the PostHog integration exposes

The integration provides tools that cover HogQL queries, events, persons, session recordings, cohorts, dashboards, experiments, actions, feature flags, insights, and annotations on PostHog US Cloud. Tools are prefixed with posthog_us_. The posthog_us_list_projects tool returns project IDs that other tools accept as project_id. Use pick() from the SDK to include only the tools your agent needs.

How it works

Create a PostHog personal API key

In PostHog, open your account settings, go to Personal API keys, and create a key with the scopes your agent needs. For example, reading feature flags requires feature_flag:read; changing them requires feature_flag:write.

Connect the credential in Guild

Go to Access & setup > Credentials, click Connect, select posthog-us, and paste the key into API Key. Guild sends the key as a bearer token in the Authorization header on every request.

Add the tools to your agent

Import PosthogUsTools from the integration package and spread it into your agent’s tools object. Use pick() to include only the tools your agent needs, such as posthog_us_list_projects and posthog_us_run_query.

Why PostHog access needs governing

PostHog personal API keys act as the user who created them, limited only by the scopes granted at creation time. An agent with a broad key can read person profiles, delete persons and their events, create or delete feature flags, and run arbitrary HogQL queries. Guild’s credential policies let you write ALLOW and DENY rules that the credential proxy enforces before any request reaches PostHog, scoped to specific operations, agents, or workspaces. Credentials can be scoped to an account, a single workspace, a single member, or one installed agent, so the right key is used in the right context. Guild stores and injects the key server-side; agent code never sees it. Without this, every agent that needed PostHog access would require its own secret management, with no central audit of what was called or blocked.

About the PostHog integration

The PostHog integration connects agents to a PostHog project on US Cloud (us.posthog.com). Agents can run HogQL queries; read events, persons, session recordings, cohorts, dashboards, experiments, and actions; manage feature flags; and create insights and annotations. The integration is guildai~posthog-us.

Authentication

Type: Personal API key
Header: Guild sends the key as a bearer token in the Authorization header

A personal API key acts as the PostHog user who created it, limited to the scopes you give it. Grant the scopes for the tools your agent uses: for example, reading feature flags needs feature_flag:read, and changing them needs feature_flag:write.

Setup

Create a personal API key

In PostHog, open your account settings, go to Personal API keys, and create a key with the scopes your agent needs.

Connect PostHog

In Guild, go to Access & setup > Credentials, click Connect, select posthog-us, and paste the key into API Key.

See Credentials for workspace, member, and agent-scoped credentials.

Usage

import { PosthogUsTools } from "@guildai-services/guildai~posthog-us"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that answers product analytics questions from PostHog",
  tools: { ...PosthogUsTools },
})

Selecting specific tools

Tools are named with the posthog_us_ prefix. posthog_us_list_projects returns each project’s ID, which other tools take as project_id. Use pick() to include only what your agent needs.

import { PosthogUsTools } from "@guildai-services/guildai~posthog-us"
import { llmAgent, pick } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that answers usage questions with HogQL",
  tools: {
    ...pick(PosthogUsTools, [
      "posthog_us_list_projects",
      "posthog_us_run_query",
    ]),
  },
})

Tools

Tools in the latest published version of guildai~posthog-us:

Tool	What it does
`posthog_us_create_annotation`	Add a dated note to the project timeline (shown on charts).
`posthog_us_create_feature_flag`	Requires the `feature_flag:write` scope.
`posthog_us_create_insight`	Create insight.
`posthog_us_delete_feature_flag`	Delete feature flag.
`posthog_us_delete_person`	Permanently deletes a person and (optionally) their associated events.
`posthog_us_get_current_user`	Returns the authenticated user, including their organizations and the current project/team.
`posthog_us_get_dashboard`	Get dashboard.
`posthog_us_get_event`	Get event.
`posthog_us_get_feature_flag`	Get feature flag.
`posthog_us_get_insight`	Get insight.
`posthog_us_get_person`	Get person.
`posthog_us_get_session_recording`	Get session recording.
`posthog_us_list_actions`	List actions.
`posthog_us_list_annotations`	List annotations.
`posthog_us_list_cohorts`	List cohorts.
`posthog_us_list_dashboards`	List dashboards.
`posthog_us_list_events`	Returns recent events for the project, most recent first.
`posthog_us_list_experiments`	List experiments.
`posthog_us_list_feature_flags`	List feature flags.
`posthog_us_list_insights`	List insights.
`posthog_us_list_persons`	Returns person profiles for the project.
`posthog_us_list_projects`	Lists the projects (teams) in the user’s current organization.
`posthog_us_list_session_recordings`	List session recordings.
`posthog_us_run_query`	Execute a query against the project’s data.
`posthog_us_update_feature_flag`	Partially update a feature flag (e.g. toggle `active`, change rollout in `filters`).

Limitations

US Cloud only. Requests go to us.posthog.com, so projects on EU Cloud or self-hosted PostHog aren’t reachable.

Frequently asked questions

Can I use this integration with PostHog EU Cloud or a self-hosted instance?

No. Requests go to us.posthog.com, so projects on EU Cloud or self-hosted PostHog are not reachable with this integration.

How do I limit an agent to read-only PostHog access?

Write a credential policy with DENY rules for mutating operations, or ALLOW rules that cover only read operations such as posthog_us_list_*, posthog_us_get_*, and posthog_us_run_query. Guild’s credential proxy enforces these rules before any request leaves Guild. See credential policies for rule syntax.

Can I give one agent a different PostHog key than the rest of my workspace?

Yes. Connect a credential dedicated to that agent from the installed agent’s page in Guild. Guild checks for an agent-dedicated credential before falling back to workspace or account credentials, so that agent uses its own key while others use the shared one.

Can agents receive PostHog webhook events through this integration?

Not yet. The catalog entry for guildai~posthog-us lists no webhook events, so agents cannot be triggered by PostHog events through this integration.

Put a governed agent on PostHog this week

Book a demo

See how teams govern agents that use PostHog.

Start free

Connect PostHog and scope your first agent.

Read: Docs: Credential policies · Credentials · Tools in agents

Overview

Code & CI/CD

Communication

Project management

Testing

Productivity

Monitoring & observability

Data

Customer support

Sales & finance

Recruiting

Query PostHog data and manage feature flags from Guild agents

Book a demo

Start free

What the PostHog integration exposes

How it works

Why PostHog access needs governing

About the PostHog integration

Authentication

Setup

Usage

Selecting specific tools

Tools

Limitations

Frequently asked questions

Put a governed agent on PostHog this week

Book a demo

Start free

Book a demo

Start free

​What the PostHog integration exposes

​How it works

​Why PostHog access needs governing

​About the PostHog integration

​Authentication

​Setup

​Usage

​Selecting specific tools

​Tools

​Limitations

​Frequently asked questions

​Put a governed agent on PostHog this week

Book a demo

Start free

​Related

What the PostHog integration exposes

How it works

Why PostHog access needs governing

About the PostHog integration

Authentication

Setup

Usage

Selecting specific tools

Tools

Limitations

Frequently asked questions

Put a governed agent on PostHog this week

Related