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

# Query PostHog Analytics and Flags From Agents

> Let agents run HogQL queries, read insights and dashboards, and manage feature flags in PostHog, with a personal API key the gateway keeps hidden.

## Overview

OneCLI connects AI agents to PostHog with a personal API key. Agents can run HogQL queries, read insights, dashboards, experiments, and session recordings, and create or update feature flags. The gateway injects the key into requests to `us.posthog.com` or `eu.posthog.com`, so your agent never sees it. Both US and EU Cloud are supported.

## What you will set up

* A PostHog personal API key with only the scopes agents need
* Automatic key injection on US or EU Cloud requests
* Per-agent, per-tool access, such as approval before flag changes

## Setup

**1. Create a personal API key**

In PostHog, go to **Settings** > **User** > **Personal API keys** and create a key. Grant only the scopes your agents need, and include **User: read** so OneCLI can show which account is connected. Keys start with `phx_`. See [Personal API keys](https://posthog.com/docs/api/personal-api-keys).

**2. Connect in OneCLI**

Open **Connections** > **PostHog** and paste your key. OneCLI detects whether it belongs to US or EU Cloud. Under **Advanced** you can add an optional connection label to tell multiple PostHog accounts apart.

![OneCLI connect dialog for PostHog, showing the required Personal API key field, a link on how to create one, an Advanced section with an optional connection label, and the Connect PostHog button.](https://mintcdn.com/chartdbinc/yFw2bbdvTPdZgMOT/images/integrations/posthog/onecli-connect-posthog.png?fit=max\&auto=format\&n=yFw2bbdvTPdZgMOT\&q=85\&s=7d8f871d76b669d2ffaf9115a5aafe72)

The PostHog connect dialog in OneCLI.

> [!WARNING]
>
> Project API keys (`phc_`) only send events and cannot read data. Use a personal API key.

## What agents can do

| Area | Description |
| - | - |
| **Queries** | Run HogQL, trends, and funnel queries over events |
| **Insights and dashboards** | Read, create, and update insights and dashboards |
| **Feature flags** | View flags and change rollout or conditions |
| **Experiments and surveys** | View experiments, results, and surveys |
| **Persons and cohorts** | Look up persons and cohorts |
| **Session recordings** | List and view session replays |
| **Annotations** | View and add annotations |
| **Error tracking** | View error tracking issues |

What a connection can actually reach follows the API key: scopes you left out when creating the key return permission errors, regardless of what OneCLI allows.

## Quick example

Replace `12345` with your project ID (shown in PostHog under **Settings** > **Project**). No auth header is needed, the gateway adds it:

```bash theme={null}
# Count yesterday's pageviews with HogQL
curl -s -X POST "https://us.posthog.com/api/projects/12345/query/" \
  -H "Content-Type: application/json" \
  -d '{"query": {"kind": "HogQLQuery", "query": "select count() from events where event = '\''$pageview'\'' and timestamp > now() - interval 1 day"}}'

# List feature flags
curl -s "https://us.posthog.com/api/projects/12345/feature_flags/"
```

On EU Cloud, use `eu.posthog.com` instead.

## Disconnecting

* In OneCLI, open **Connections** > **PostHog** and remove the connection.
* Then delete the key in PostHog under **Settings** > **User** > **Personal API keys**.

## Controlling access

Access is per agent: [grant](https://onecli.sh/docs/guides/agent-access.md) the connection to each agent that needs it, choosing per tool what runs freely, what needs human approval, and what stays blocked. For example, let an agent run queries but require approval before it changes a feature flag. Organization [rules](https://onecli.sh/docs/guides/rules.md) add guardrails on top, like rate limits. Everything is checked before credential injection, so a blocked request never reaches PostHog.

## FAQ

> [accordion] How do I rotate my PostHog API key?
>
> Create a new personal API key in PostHog, then paste it into **Connections** > **PostHog**. Agents pick it up automatically. Then delete the old key.

> [accordion] How do I keep the key out of the agent's context?
>
> Store it in OneCLI. The gateway injects it at the proxy, so the agent never holds the `phx_` key. See [How it works](https://onecli.sh/docs/how-it-works.md).

> [accordion] Can I use a project API key?
>
> No. Project API keys (`phc_`) only send events and cannot read data. Use a personal API key.


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