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

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Query PostHog data and manage feature flags from Guild agents

> Connect Guild agents to PostHog US Cloud. Run HogQL queries, read analytics data, manage feature flags, and create insights with governed credentials.

<div className="guild-lockup">
  <span className="guild-eyebrow">Integrations · PostHog</span>
</div>

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.

<CardGroup cols={2}>
  <Card title="Book a demo" icon="calendar" href="https://guild-ai.cal.com/gtm/meeting-with-guild.ai">
    See how teams govern agents that use PostHog.
  </Card>

  <Card title="Start free" icon="rocket" href="https://app.guild.ai">
    Connect PostHog and scope your first agent.
  </Card>
</CardGroup>

## 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

<Steps>
  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>
</Steps>

## 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](/platform/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](/platform/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

<Steps>
  <Step title="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.</Step>
  <Step title="Connect PostHog">In Guild, go to **Access & setup > Credentials**, click **Connect**, select **posthog-us**, and paste the key into **API Key**.</Step>
</Steps>

See [Credentials](/platform/credentials) for workspace, member, and agent-scoped credentials.

## Usage

```typescript theme={null}
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.

```typescript theme={null}
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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/platform/credential-policies) for rule syntax.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Put a governed agent on PostHog this week

<CardGroup cols={2}>
  <Card title="Book a demo" icon="calendar" href="https://guild-ai.cal.com/gtm/meeting-with-guild.ai">
    See how teams govern agents that use PostHog.
  </Card>

  <Card title="Start free" icon="rocket" href="https://app.guild.ai">
    Connect PostHog and scope your first agent.
  </Card>
</CardGroup>

## Related

**Read:** Docs: [Credential policies](/platform/credential-policies) · [Credentials](/platform/credentials) · [Tools in agents](/sdk/tools)