canonical: https://jentic.com/apis/posthog.com/posthog

# PostHog API

Jentic publishes the only available OpenAPI specification for PostHog API, keeping it validated and agent-ready. Capture events, query persons and their properties, build and retrieve insights (trends, funnels, retention), manage dashboards, control feature flags, and organize users into behavioral cohorts - all within an open-source product analytics platform. The API also supports event capture via dedicated endpoints, feature flag evaluation via the decide endpoint, and project-level organization management.

## For AI agents

Capture product events, query behavioral insights and funnels, evaluate feature flags, and manage cohorts and dashboards for open-source product analytics.

## Scope

Does not handle customer data routing, email notifications, or payment processing - use for product analytics, feature flags, and behavioral cohorts only.

## Capabilities

- Capture individual and batch events from server-side applications with user and property metadata
- Query saved insights including trends, funnels, retention, and lifecycle reports by project
- Evaluate feature flags for specific users via the decide endpoint to control rollout
- Build and manage behavioral cohorts based on event sequences and person properties
- Create and organize dashboards that aggregate multiple insights into unified views
- Define and track custom actions based on event matching rules for conversion measurement
- Retrieve person profiles with full event history and property values

## Use cases

### AI Agent Product Analytics Integration

AI agents query PostHog insights endpoints to retrieve trend data, funnel conversions, and retention metrics programmatically without manual dashboard interaction. Through Jentic, an agent discovers the needed analytics operation by intent, receives the schema, and executes queries against PostHog's project-scoped API. This enables automated reporting, alerting on metric changes, and AI-powered product recommendations - all with setup in minutes rather than days.

Example prompt: GET insights from /api/projects/{project_id}/insights filtered by type 'TRENDS' and return the top 5 insights with their current values

### Feature Flag Management and Evaluation

Control feature rollouts by creating feature flags with percentage-based or property-based targeting rules, then evaluate them for specific users via the decide endpoint. The API supports multivariate flags, gradual rollouts, and kill switches. Teams use this to gate features for beta users, run A/B tests, and instantly disable problematic features without code deployment.

Example prompt: Create a new feature flag via POST /api/projects/{project_id}/feature_flags with 50% rollout, then evaluate it for user 'user-123' via POST /decide

### Server-Side Event Capture Pipeline

Ingest events from backend services using the capture and batch endpoints, which accept event name, distinct_id, properties, and timestamp. This enables tracking of server-side actions that cannot be captured client-side - purchase completions, subscription renewals, API usage, and background job results. The batch endpoint accepts arrays of events for high-throughput ingestion.

Example prompt: POST a batch of 10 events to the /batch endpoint with event name 'subscription_renewed', distinct_id, and properties including plan_type and amount

### Behavioral Cohort Analysis

Define cohorts based on event sequences, person properties, or combinations of behavioral criteria, then query which persons belong to each cohort. This powers targeted feature rollouts (release to 'power users' cohort), personalized messaging, and churn analysis by comparing behavioral patterns of retained versus churned user groups.

Example prompt: Create a new cohort via POST /api/projects/{project_id}/cohorts with criteria matching users who performed 'purchase' more than 3 times in the last 30 days

### Dashboard and Insight Management

Programmatically create dashboards, add insight tiles, and retrieve dashboard data for automated reporting workflows. Each insight can be a trend, funnel, retention, lifecycle, or path analysis. Teams use this to build project-specific dashboards, clone template dashboards across projects, and export insight data to external reporting systems.

Example prompt: Create a new dashboard via POST /api/projects/{project_id}/dashboards with name 'Weekly KPIs', then retrieve all insights linked to it

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /capture | Capture a single event with properties |
| POST | /batch | Batch-ingest multiple events in one request |
| POST | /decide | Evaluate feature flags for a user |
| GET | /api/projects/{project_id}/insights | List saved insights (trends, funnels, retention) |
| POST | /api/projects/{project_id}/feature_flags | Create a new feature flag |
| GET | /api/projects/{project_id}/persons | List persons with properties and events |
| GET | /api/projects/{project_id}/dashboards | List project dashboards |
| POST | /api/projects/{project_id}/cohorts | Create a behavioral cohort |

## Key resources

- **Events** — Capture individual and batch events from client and server applications
- **Insights** — Query and create trend, funnel, retention, and lifecycle analytics
- **Feature Flags** — Create flags with targeting rules and evaluate them per user
- **Persons** — Retrieve user profiles with properties and event history
- **Dashboards** — Create and manage dashboards aggregating multiple insights
- **Cohorts** — Define behavioral user segments based on event and property criteria
- **Actions** — Define event matching rules for conversion and goal tracking
- **Annotations** — Mark timeline events for releases, incidents, and milestones

## Why Jentic

- **Setup:** Wiring the PostHog API by hand means learning its bearer token auth and choosing the right regional host ({region}.posthog.com) yourself. Through Jentic you install once, import the PostHog API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** PostHog puts the project id in the URL path (/api/projects/{project_id}/...), so a rule can pin your agent to one project: you choose the operations it may call, so writes like creating feature flags or cohorts are not included unless you add them.
- **Credential handling:** Your PostHog API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'evaluate a feature flag for a user' or 'list project insights', and Jentic returns the matching PostHog operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Mixpanel API** — Mixpanel provides SaaS-hosted product analytics with JQL custom queries but without feature flags or session recording
- **Amplitude API** — Amplitude offers behavioral analytics with revenue metrics and user search but as a closed-source SaaS platform
- **Plausible API** — Plausible provides privacy-focused web analytics for page views and referrers, complementing PostHog's deeper product analytics
- **Segment API** — Segment routes event data from multiple sources to PostHog and other destinations

## FAQ

### Why is there no official OpenAPI spec for PostHog API?

PostHog does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call PostHog API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the PostHog API use?

The PostHog API uses Bearer token authentication with a personal API key or project API key passed in the Authorization header. The capture and batch endpoints alternatively accept the project API key in the request body. Through Jentic, your API key is stored encrypted in the credential vault and agents receive scoped access without the raw key entering their context.

### Can I evaluate feature flags for specific users with the PostHog API?

Yes. POST to the /decide endpoint with a distinct_id and the API key. The response returns all active feature flags for that user along with their variant values, enabling server-side feature gating without client-side SDK installation.

### What are the rate limits for the PostHog API?

PostHog Cloud enforces rate limits of approximately 600 requests per minute for query endpoints (insights, persons, dashboards). The event capture endpoints (/capture and /batch) have higher throughput limits. Self-hosted instances can configure custom rate limits via environment variables.

### How do I query trend insights through the PostHog API via Jentic?

Search Jentic for 'query product analytics trends posthog' to discover the /api/projects/{project_id}/insights operation. Load the schema, filter by insight type 'TRENDS', and execute. The endpoint returns trend data with date-indexed values. Install the SDK with pip install jentic to get started.

### Can I batch-ingest events from a backend service?

Yes. POST to the /batch endpoint with a JSON body containing an api_key and a batch array of event objects. Each event requires an event name, distinct_id, and properties object. The batch endpoint is designed for high-throughput server-side ingestion without per-event HTTP overhead.

### How do I create a behavioral cohort programmatically?

POST to /api/projects/{project_id}/cohorts with a name and groups array specifying behavioral criteria - such as users who performed a specific event more than N times within a date range. The cohort is then available for insight filtering, feature flag targeting, and export.

### Can I limit what my agent is allowed to do with the PostHog API?

Yes. Because you run Jentic One yourself, your own rules decide which PostHog operations and credentials the agent may use. Since PostHog puts the project id in the URL path (/api/projects/{project_id}/...), you can pin the agent to a single project and grant only read operations such as listing insights, persons, and dashboards. Write operations like creating a feature flag (POST /feature_flags) or a cohort (POST /cohorts) stay unavailable until you explicitly add them.