PostHog API Skill
Interact with PostHog via its REST API. Two types of endpoints:
- - Public (POST-only, project API key): capture events, evaluate flags — no rate limits
- Private (personal API key): query, CRUD for all resources — rate limited
Setup
- 1. Get personal API key: https://us.posthog.com/settings/user-api-keys
- Get project ID: https://us.posthog.com/settings/project#variables
- Set env vars:
export POSTHOG_API_KEY="phx_..."
export POSTHOG_PROJECT_ID="12345"
export POSTHOG_PROJECT_API_KEY="phc_..." # optional, for capture/flags
# For EU Cloud:
# export POSTHOG_HOST="https://eu.posthog.com"
# export POSTHOG_INGEST_HOST="https://eu.i.posthog.com"
- 4. Verify: INLINECODE0
Helper Script
INLINECODE1 wraps common operations. Run bash scripts/posthog.sh help for full usage.
Examples
CODEBLOCK1
Key Concepts
Two API types
- - Public endpoints (
/i/v0/e/, /batch/, /flags): Use project API key in body. No auth header. No rate limits. - Private endpoints (
/api/projects/:project_id/...): Use personal API key via Authorization: Bearer. Rate limited.
HogQL Queries
The query endpoint (
POST /api/projects/:project_id/query/) is the most powerful way to extract data. Uses SQL-like HogQL syntax against tables:
events,
persons,
sessions,
groups, plus data warehouse tables.
Always include time ranges and LIMIT. Use timestamp-based pagination for large exports.
Rate Limits (private endpoints)
| Type | Limit |
|---|
| Analytics (insights, persons, recordings) | 240/min, 1200/hr |
| Query endpoint |
2400/hr |
| Feature flag local evaluation | 600/min |
| Other CRUD | 480/min, 4800/hr |
Limits apply per organization. On 429: back off and retry.
Domains
| Cloud | Public | Private |
|---|
| US | INLINECODE13 | INLINECODE14 |
| EU |
eu.i.posthog.com |
eu.posthog.com |
Events API (deprecated)
The
/api/projects/:project_id/events/ endpoint is deprecated. Use HogQL queries or batch exports instead.
Direct curl
CODEBLOCK2
Full API Reference
See references/api-endpoints.md for complete endpoint listing with parameters, body schemas, scopes, and response formats.
Sections: Public Endpoints (Capture, Batch, Flags), Private Endpoints (Persons, Feature Flags, Insights, Dashboards, Annotations, Cohorts, Experiments, Surveys, Actions, Session Recordings, Users, Definitions), Query API (HogQL).
PostHog API 技能
通过 REST API 与 PostHog 交互。两种端点类型：
- - 公共端点（仅 POST，项目 API 密钥）：捕获事件、评估标志——无速率限制
- 私有端点（个人 API 密钥）：查询、CRUD 所有资源——有速率限制
设置
- 1. 获取个人 API 密钥：https://us.posthog.com/settings/user-api-keys
- 获取项目 ID：https://us.posthog.com/settings/project#variables
- 设置环境变量：
bash
export POSTHOG
APIKEY=phx_...
export POSTHOG
PROJECTID=12345
export POSTHOG
PROJECTAPI
KEY=phc... # 可选，用于捕获/标志
# 对于 EU 云：
# export POSTHOG_HOST=https://eu.posthog.com
# export POSTHOG
INGESTHOST=https://eu.i.posthog.com
- 4. 验证：bash scripts/posthog.sh whoami
辅助脚本
scripts/posthog.sh 封装了常用操作。运行 bash scripts/posthog.sh help 查看完整用法。
示例
bash
捕获事件
bash scripts/posthog.sh capture signup user_123 {plan:pro}
评估功能标志
bash scripts/posthog.sh evaluate-flags user_123
HogQL 查询——最近 7 天的热门事件
bash scripts/posthog.sh query SELECT event, count() FROM events WHERE timestamp >= now() - INTERVAL 7 DAY GROUP BY event ORDER BY count() DESC LIMIT 20
列出用户
bash scripts/posthog.sh list-persons 10 | jq .results[] | {name, distinct_ids}
列出功能标志
bash scripts/posthog.sh list-flags | jq .results[] | {id, key, active}
创建功能标志
echo {key:new-dashboard,name:New Dashboard,active:true,filters:{groups:[{rollout_percentage:50}]}} | \
bash scripts/posthog.sh create-flag
列出仪表板
bash scripts/posthog.sh list-dashboards | jq .results[] | {id, name}
关键概念
两种 API 类型
- - 公共端点（/i/v0/e/、/batch/、/flags）：在请求体中使用项目 API 密钥。无需认证头。无速率限制。
- 私有端点（/api/projects/:project_id/...）：通过 Authorization: Bearer 使用个人 API 密钥。有速率限制。
HogQL 查询
查询端点（POST /api/projects/:project_id/query/）是提取数据最强大的方式。使用类似 SQL 的 HogQL 语法，针对表：events、persons、sessions、groups，以及数据仓库表。
始终包含时间范围和 LIMIT。对于大量导出，使用基于时间戳的分页。
速率限制（私有端点）
| 类型 | 限制 |
|---|
| 分析（洞察、用户、录制） | 240/分钟，1200/小时 |
| 查询端点 |
2400/小时 |
| 功能标志本地评估 | 600/分钟 |
| 其他 CRUD | 480/分钟，4800/小时 |
限制按组织应用。遇到 429：退避重试。
域名
| 云 | 公共 | 私有 |
|---|
| 美国 | us.i.posthog.com | us.posthog.com |
| 欧盟 |
eu.i.posthog.com | eu.posthog.com |
事件 API（已弃用）
/api/projects/:project_id/events/ 端点已弃用。请改用 HogQL 查询或批量导出。
直接使用 curl
bash
私有端点
curl -H Authorization: Bearer $POSTHOG
APIKEY \
$POSTHOG
HOST/api/projects/$POSTHOGPROJECT
ID/featureflags/
HogQL 查询
curl -H Authorization: Bearer $POSTHOG
APIKEY \
-H Content-Type: application/json \
-X POST -d {query:{kind:HogQLQuery,query:SELECT count() FROM events WHERE timestamp >= now() - INTERVAL 1 DAY}} \
$POSTHOG
HOST/api/projects/$POSTHOGPROJECT_ID/query/
捕获事件（公共）
curl -H Content-Type: application/json \
-X POST -d {api
key:$POSTHOGPROJECT
APIKEY,event:test,distinct_id:u1} \
$POSTHOG
INGESTHOST/i/v0/e/
完整 API 参考
参见 references/api-endpoints.md 获取包含参数、请求体模式、作用域和响应格式的完整端点列表。
章节：公共端点（捕获、批量、标志）、私有端点（用户、功能标志、洞察、仪表板、注释、群体、实验、调查、操作、会话录制、用户、定义）、查询 API（HogQL）。
