VX Agents

OpenAPI Marketplace · Marketing & Analytics

PostHog Product Analytics

v1.0.0 · 13 endpoints · 0 connections · shared by vx.ai

How many people signed up last week, and where did they drop off? Ask PostHog directly with HogQL queries, read saved insights and dashboards, look up persons and cohorts, check feature flag rollouts, and pin an annotation on the charts when you ship.

Connect this API to an AI agent Browse all specs

What you can do with PostHog Product Analytics via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
GET /api/users/{uuid}/ getCurrentUser Get your user, current organization and current project (use uuid @me)
GET /api/organizations/{organization_id}/projects/ listProjects List the projects in an organization with their ids
POST /api/projects/{project_id}/query/ runQuery Run a HogQL (SQL) or trends/funnel query on events and persons
GET /api/projects/{project_id}/insights/ listInsights Find saved insights (charts) by name, tag or dashboard
GET /api/projects/{project_id}/insights/{id}/ getInsight Get a saved insight with its query and latest results
GET /api/projects/{project_id}/dashboards/ listDashboards List dashboards
GET /api/projects/{project_id}/dashboards/{id}/ getDashboard Get a dashboard with its insight tiles
GET /api/projects/{project_id}/persons/ listPersons Look up persons by email, distinct id or properties
GET /api/projects/{project_id}/cohorts/ listCohorts List cohorts (saved groups of users)
GET /api/projects/{project_id}/annotations/ listAnnotations List annotations (release notes on charts)
POST /api/projects/{project_id}/annotations/ createAnnotation Add an annotation at a date, e.g. a launch or campaign start
GET /api/projects/{project_id}/feature_flags/ listFeatureFlags List feature flags and whether they are active
GET /api/projects/{project_id}/feature_flags/{id}/ getFeatureFlag Get a feature flag's rollout and release conditions

Authentication

posthogPersonalKey

Bearer token — sent as Authorization: Bearer <token>

PostHog personal API key sent as Authorization: Bearer phx_.... Do not use the project API key (phc_...): it can only send events.

How to get a credential

  1. In PostHog, open Settings > Personal API keys (click your avatar > Settings).
  2. Click Create personal API key, name it (e.g. "VX Agents").
  3. Limit it to the organization or project you want, and select the scopes below.
  4. Copy the key (phx_...) now: PostHog shows it only once.
  5. EU Cloud project? Change the server to https://eu.posthog.com.

Permissions used

Scope Operations
user:read getCurrentUser
project:read listProjects
query:read runQuery
insight:read listInsights, getInsight
dashboard:read listDashboards, getDashboard
person:read listPersons
cohort:read listCohorts
annotation:read listAnnotations
annotation:write createAnnotation
feature_flag:read listFeatureFlags, getFeatureFlag

Common errors

  • 401 Unauthorized: wrong key, a project key (phc_) instead of a personal key, or the wrong region (US vs EU).
  • 403 Forbidden: the key lacks the scope, or it is limited to a different project or organization.
  • 400 Bad Request: invalid HogQL or query JSON. The response says which part failed.
  • 429 Too Many Requests: analytics endpoints allow about 240 requests a minute and 1200 an hour. Wait and retry.

Store the key as a VX Agents credential (bearer token) and never paste it into chat.

Usage guide

Setup

  • Credential: a PostHog personal API key (phx_...) as a bearer token, with the read scopes listed in the auth docs (plus annotation:write to add annotations).
  • Region: https://us.posthog.com by default. EU Cloud projects must use https://eu.posthog.com.
  • Find the project id once: getCurrentUser with uuid=@me returns team.id (current project) and organization.id. listProjects lists the rest. Pin project_id as a preset parameter.

Answer a product question

  1. Check for a saved answer first: listInsights with search (e.g. "signups") or listDashboards, then getInsight / getDashboard to read the stored results.
  2. If nothing fits, run runQuery with {"query": {"kind": "HogQLQuery", "query": "SELECT ..."}}. Useful tables: events (event, timestamp, distinct_id, properties.$current_url, person.properties.email) and persons. Example: SELECT toStartOfDay(timestamp) AS day, count() FROM events WHERE event = 'user signed up' AND timestamp > now() - INTERVAL 14 DAY GROUP BY day ORDER BY day.
  3. Results come back as columns + results rows. Summarize them, and name the date range and time zone.
  4. Who is behind the numbers: listPersons with email, distinct_id or search. listCohorts shows saved segments.
  5. Rollout questions: listFeatureFlags (active, search) and getFeatureFlag for its filters and rollout percentage.
  6. After a launch or campaign, createAnnotation with content, date_marker (ISO 8601) and scope=project so it shows on every chart. Confirm the text and date with the user first.

Good to know

  • API queries return 100 rows unless you add your own LIMIT (max 50,000). Always add LIMIT and a time filter: scanning all events is slow and uses the read budget.
  • Rate limits: about 240/minute and 1200/hour on analytics endpoints, 2400/hour for runQuery.
  • refresh=blocking uses fresh cache or computes now. force_blocking always recomputes.
  • Lists page with limit and offset. Follow next when it is set.
  • Event names are case-sensitive. Find them with SELECT event, count() FROM events GROUP BY event ORDER BY count() DESC LIMIT 50.
  • Source: PostHog API reference (https://posthog.com/docs/api), checked 2026-10-16.

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “PostHog Product Analytics” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.

Related APIs