PostHog API 技能

通过 PostHog 的 REST API 与其交互。包含两类端点：

• 公共端点（仅支持 POST 请求，使用项目 API 密钥）：用于捕获事件、评估功能标志（feature flags）——无速率限制
• 私有端点（使用个人 API 密钥）：用于查询及所有资源的增删改查（CRUD）操作——受速率限制

配置步骤

1. 获取个人 API 密钥：https://us.posthog.com/settings/user-api-keys
2. 获取项目 ID：https://us.posthog.com/settings/project#variables
3. 设置环境变量：

   export POSTHOG_API_KEY="phx_..."
   export POSTHOG_PROJECT_ID="12345"
   export POSTHOG_PROJECT_API_KEY="phc_..."  # 可选，仅用于 capture/flags
   # 若使用 EU Cloud：
   # export POSTHOG_HOST="https://eu.posthog.com"
   # export POSTHOG_INGEST_HOST="https://eu.i.posthog.com"
   

4. 验证配置：bash scripts/posthog.sh whoami

辅助脚本

scripts/posthog.sh 封装了常用操作。运行 bash scripts/posthog.sh help 查看完整用法。

示例

# 捕获一个事件
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"

# 列出人员（persons）
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

# 列出仪表板（dashboards）
bash scripts/posthog.sh list-dashboards | jq '.results[] | {id, name}'

核心概念

两类 API

• 公共端点（/i/v0/e/、/batch/、/flags）：在请求体中传入项目 API 密钥，无需认证头（Authorization header），无速率限制。
• 私有端点（/api/projects/:project_id/...）：通过 Authorization: Bearer 方式传入个人 API 密钥，受速率限制。

HogQL 查询

查询端点（POST /api/projects/:project_id/query/）是提取数据最强大的方式。它使用类 SQL 的 HogQL 语法，可查询如下表：events、persons、sessions、groups，以及数据仓库中的表。

务必始终指定时间范围和 LIMIT。对于大规模导出，请使用基于时间戳的分页机制。

速率限制（私有端点）

速率限制按组织（organization）粒度生效。遇到 HTTP 429 响应时，请退避并重试。

域名

事件 API（已弃用）

/api/projects/:project_id/events/ 端点已被弃用。请改用 HogQL 查询或批量导出（batch exports）替代。

直接使用 curl

# 私有端点
curl -H "Authorization: Bearer $POSTHOG_API_KEY" 
  "$POSTHOG_HOST/api/projects/$POSTHOG_PROJECT_ID/feature_flags/"

# HogQL 查询
curl -H "Authorization: Bearer $POSTHOG_API_KEY" 
  -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/$POSTHOG_PROJECT_ID/query/"

# 捕获事件（公共端点）
curl -H "Content-Type: application/json" 
  -X POST -d '{"api_key":"'$POSTHOG_PROJECT_API_KEY'","event":"test","distinct_id":"u1"}' 
  "$POSTHOG_INGEST_HOST/i/v0/e/"

完整 API 参考文档

详见 references/api-endpoints.md，其中包含全部端点的完整列表，涵盖参数说明、请求体结构（body schemas）、权限范围（scopes）及响应格式。

章节划分包括：公共端点（Capture、Batch、Flags），私有端点（Persons、Feature Flags、Insights、Dashboards、Annotations、Cohorts、Experiments、Surveys、Actions、Session Recordings、Users、Definitions），以及查询 API（HogQL）。