PostHog 端点在客户端代码中的消费指南:鉴权、变量载荷、类型化客户端与限流处理
PostHog 端点在客户端代码中的消费指南:鉴权、变量载荷、类型化客户端与限流处理
导读
本文是 PostHog 端点(Endpoint)的“调用方(caller-side)”集成指南:PostHog 将保存好的 HogQL 或 Insight 查询暴露为可调用的 API 路由,本文讲解如何从移动端、服务端、客户看板或下游管道中安全、正确地调用这些端点。读完本文,你将掌握端点 URL 与请求载荷的完整形态、个人 API Key 的正确使用姿势、materialised(物化)端点对变量的强制要求、基于 OpenAPI 规范生成类型化客户端的流程,以及限流与错误响应的处理策略。本文源自仓库中的 consuming-endpoints-from-client-code/SKILL.md,并辅以 products/endpoints 后端的源码实现进行印证。
适用场景:什么时候使用这套指南
本文面向的是已有端点、需要从外部代码库接入的调用方,常见诉求包括:
- “我该怎么调用我的端点?一次请求长什么样?”
- “为这个端点生成类型化的 TypeScript / Python / Go 客户端”
- “调用端点时收到 401”的鉴权问题
- “省略了
user_id时端点拒绝我的调用”——这通常涉及物化端点的变量强制要求 - “如何处理限流(rate limit)?”
注意:如果需求是创建端点,请先参考创建侧的指南 creating-an-endpoint/SKILL.md。本文全程不修改任何 PostHog 代码,只做外部接入。
可用工具:端点相关的 MCP 工具
PostHog 通过 MCP 工具暴露端点相关能力,其定义见 products/endpoints/mcp/tools.yaml,与端点消费直接相关的有三个:
| 工具 | 用途 |
|---|---|
endpoint-get |
获取指定端点的完整配置,包括查询形态(query shape)与必需的变量 |
endpoint-openapi-spec |
获取单个端点的 OpenAPI 3.0 规范,可直接喂给代码生成器 |
endpoint-run |
对端点做一次实时调用,用于在分享给用户应用之前确认载荷可用 |
所有端点相关工具都要求 endpoint:read scope(写入类工具如 endpoint-create、endpoint-update、endpoint-delete 则要求 endpoint:write),这与下文“鉴权”一节的要求一致。
端点 URL 的完整形态
/api/projects/{team_id}/endpoints/{name}/run
team_id:项目 ID(数字)。可在 PostHog 的项目设置中查看,若用户不知道,可通过projects-get获取。name:端点名称,不确定时可用endpoints-get-all列出全部端点。- 结尾的
/run是必需的。
在源码中,端点路由注册于项目级路由之下(见 routes.py:routers.projects.register(r"endpoints", EndpointViewSet, "project_endpoints", <a href="https://link.gitcode.com/i/56755204b4cf5c9f1259af77f0a7f00c" target="_blank">"team_id"])),而 run 是 EndpointViewSet 上的一个 detail action(见 [api.py 的 @action(methods=["GET", "POST"], detail=True)),因此 URL 形态与上文的 /{name}/run 完全吻合。
方法选择:POST 优先
POST 是规范方法;GET 在无请求体的简单场景下也可用,但优先使用 POST——变量放在请求体中。从源码看,run action 同时声明了 GET 和 POST 两种方法,但 limit、offset、version 等参数既可从 body 读取也可从 query 读取(见 api.py),而 variables 等复杂载荷只存在于 body。
鉴权:个人 API Key 与服务端-only 原则
端点使用**个人 API Key(personal API key)**进行认证,请求头格式为:
Authorization: Bearer <key>
Key 是有作用域(scoped)的——对于端点,Key 至少需要 endpoint:read 权限。错误排查口诀:
- 收到 403:通常缺少 scope(或端点在另一个项目里);
- 收到 401:Key 缺失或格式错误。
从源码看,EndpointViewSet 的 scope_object = "endpoint",而 run 在内的读取类 action 全部挂在 scope_object_read_actions 列表中(见 api.py),即 endpoint:read scope 即可覆盖执行(run)与查看类操作。
安全红线:绝不要把个人 API Key 放进面向终端用户的客户端代码(移动 App、浏览器 JS)。个人 API Key 授予的是带作用域的账户级访问权限。面向客户的应用应当经由用户自己的后端转发请求,由后端保管 Key。
补充一点源码层面的细节:run 是公开的执行 API,认证上仍要求登录、endpoint:read scope 与项目成员身份,但会跳过资源级访问控制,仅保留对象级(单个端点)的显式拒绝逻辑(见 api.py)。项目级 Secret API Key(PSAK)只允许用于 run 动作(psak_allowed_actions = ["run"]),且 PSAK 的 scope 是项目级的,会刻意绕过对象级访问控制。
请求载荷(payload)的字段详解
{
"variables": { "code_name_1": value, "code_name_2": value },
"limit": 100,
"offset": 0,
"refresh": "cache"
}
| 字段 | 说明 |
|---|---|
variables |
键为变量的 code_name(HogQL 端点);对于带 breakdown 的 Insight 端点,键为 breakdown 属性名 |
limit |
返回的最大行数 |
offset |
跳过的行数,仅 HogQL 端点支持 |
refresh |
"cache"(缓存足够新鲜时直接返回缓存结果)、"force"(总是重新计算)、"direct"(绕过物化直接查原始数据,仅物化端点可用)。默认 "cache" |
调用 endpoint-get 可查看确切的变量形态:响应中包含带声明变量的查询定义,每个变量的 code_name 就是客户端应发送的键。这与 MCP 工具 endpoint-run 的参数覆盖说明一致(见 tools.yaml):HogQL 端点按 code_name 传参(如 {"event_name": "$pageview"}),带 breakdown 的 Insight 端点则用 breakdown 属性名作为键。
另外注意请求体中的 version 字段或 ?version=N 查询参数可用于指定调用某个端点版本(body 优先于 query 参数,见 api.py 的 _parse_version_param)。源码对参数还有额外校验:limit 最小为 1,offset 最小为 0,且设置了 offset 就必须同时设置 limit,否则返回 400(见 api.py)。
物化端点:所有变量都必须传
如果 endpoint-get 返回当前版本的 is_materialized: true,则该端点每次调用都必须传入每一个声明的变量。这是一条安全边界——如果没有过滤条件,一次调用就会返回整个预聚合(pre-aggregated)数据集。
典型症状:应用在端点未物化时一切正常,启用物化后开始返回 400;错误消息会列出缺失的变量。这条规则也体现在创建侧的校验逻辑中——源码在启用物化时会校验查询的可物化性(见 validation.py)。
已知限制与反馈渠道:物化端点上“可选/部分变量”是目前已知的限制,PostHog 团队计划解除。如果“每个变量都必须传”阻碍了使用场景,可以通过 agent-feedback 工具反馈——这类需求信号正是团队排定优先级的主要依据。
生成类型化客户端:OpenAPI 规范 + 代码生成器
每个端点通过 endpoint-openapi-spec 暴露自己的 OpenAPI 3.0 规范。在源码中对应 openapi_spec action,路由为 openapi.json,支持 ?version=N 为指定版本生成规范(见 api.py)。拿到 spec 后喂给代码生成器:
| 语言 | 工具 | 命令形态 |
|---|---|---|
| TypeScript | @hey-api/openapi-ts |
openapi-ts -i spec.json -o ./generated |
| TypeScript | openapi-generator-cli |
openapi-generator-cli generate -i spec.json -g typescript-fetch -o ./generated |
| Python | openapi-generator-cli |
openapi-generator-cli generate -i spec.json -g python -o ./generated |
| Go | oapi-codegen |
oapi-codegen -package=client spec.json > client.go |
生成的客户端会为用户提供变量载荷与响应形态的类型。当端点的查询发生变化时需重新生成(每个新版本可能引入或移除变量)。
多个端点的处理:每个端点生成一份 spec,可以合并生成一个客户端,也可以每个端点单独生成一个客户端、并排使用。
响应形态(Response shape)
一个典型的成功响应:
{
"results": [[...], [...]],
"columns": ["col_a", "col_b"],
"types": ["Int64", "String"],
"hasMore": false,
"name": "endpoint_name",
"endpoint_version": 4,
"endpoint_version_created_at": "2026-01-15T..."
}
results是行数组,每行是按columns顺序排列的单元格值数组;endpoint_version告诉客户端实际运行的是哪个版本——这对日志记录、以及用?version=N固定到已知版本都很有用。
对于 Insight 端点,响应形态取决于查询类型(TrendsQuery、LifecycleQuery、RetentionQuery)——OpenAPI 规范会捕获当前版本的正确形态。无法物化的 Insight 类型(如 FunnelsQuery)仍然返回其内联(inline)结果形态。
从 PostHog CLI 调用端点
本地测试、脚本或 CI 场景下,仓库自带的 posthog-cli 可以直接调用端点,无需手写 HTTP:
posthog-cli exp endpoints run—— 执行端点(基于本地 YAML 定义);posthog-cli exp endpoints {list,get,pull,push,diff}—— 查看端点,或将端点作为 YAML 文件纳入版本管理(GitOps 风格)。
CLI 命令的实现见 cli/src/commands.rs(endpoints_list / endpoints_get / endpoints_open / endpoints_run / endpoints_push / endpoints_pull / endpoints_diff),其中 push 还支持 --dry-run 预览变更。
鉴权使用同一个个人 API Key,可通过 posthog-cli login 或环境变量 POSTHOG_CLI_API_KEY / POSTHOG_CLI_PROJECT_ID / POSTHOG_CLI_HOST 配置。注意这些命令位于 exp(experimental)命名空间下,API 可能变化。
需要处理的错误响应
| 状态码 | 触发场景 | 处理方式 |
|---|---|---|
| 400 | 物化端点缺少必需变量,或变量类型非法 | 展示错误消息;修正调用 |
| 401 | 个人 API Key 缺失 / 错误 | 检查 Authorization 头 |
| 403 | Key 缺少 endpoint:read scope,或端点在另一个项目中 |
调整 Key 的 scope |
| 404 | 端点名拼写错误,或端点未激活 | 确认名称;检查 is_active |
| 429 | 触发限流——限额按团队而非按端点(见下方说明) | 指数退避重试;客户端尽可能缓存响应 |
| 5xx | 查询执行失败(ClickHouse 错误、超时等) | 带退避重试;持续失败则移交 diagnosing-endpoint-performance 处理 |
从源码看,run 中版本号不存在会返回带 current_version 的 404(api.py),offset 缺 limit 会返回 400,非法数值参数同样返回 400 并记录 rejected run 日志。
完整工作流
- 确认端点名称。不知道的话,可用
execute-sql查询system.data_modeling_endpoints表,或使用endpoints-get-all。 - 用
endpoint-get查看完整形态:变量、物化状态、查询类型。 - 确定鉴权姿态:个人 API Key 放在服务端,绝不放在客户端。
- 若用户需要生成类型,调用
endpoint-openapi-spec,把 spec 交给用户,并按语言推荐生成器。 - 根据变量声明构造一个示例请求载荷,并走一遍测试调用。
- 可选:用本技能的
endpoint-run实时确认载荷可用。 - 收尾时交代处理要点:物化变量规则、限流形态、用
?version=N固定版本。
实战示例:从 Node.js 后端调用物化端点
用户:"我想从我的 Node.js 后端调用 monthly_active_users,能帮我接线并带上类型吗?"
Agent 步骤:
- endpoint-get monthly_active_users → HogQL,变量:lookback_days
(int,默认 30)、org_id(string,无默认值)、is_materialized: true
- "先说明两件事:
1. 这个端点是物化的,所以 lookback_days 和 org_id 每次调用都必须传,
缺参数会被拒绝。
2. 你需要一个带 endpoint:read scope 的个人 API Key,放在服务端环境变量
PH_API_KEY 里——绝不要发布到客户端代码中。"
- endpoint-openapi-spec monthly_active_users → 返回 spec
- "这是 spec。放进你的仓库然后运行:
pnpm dlx @hey-api/openapi-ts -i spec.json -o ./generated/posthog
这会生成类型化客户端函数。
最小调用长这样:
POST /api/projects/12345/endpoints/monthly_active_users/run
Authorization: Bearer <PH_API_KEY>
Content-Type: application/json
{ 'variables': { 'org_id': 'acme', 'lookback_days': 30 } }
响应包含 columns 和 rows——你的客户端会从生成的类型里自动识别。
需要我先做一次示例调用来验证载荷可用吗?"
重要注意事项汇总
-
个人 API Key 只能用于服务端。 绝不放进移动 App 或浏览器 JS。
-
查询变化时重新生成客户端。 每个新的端点版本都可能增删变量——重新拉取 spec 保持类型同步。
-
物化端点会拒绝缺变量的调用。 这是有意为之。如果用户在启用物化后报告 400,问题出在调用方,而不是端点。
-
固定版本,不要依赖 “latest”。 始终用
?version=N调用。不带版本参数时会运行最新激活版本,因此未来一次查询编辑(会切出新版本)可能悄然改变调用方的结果。在验证新版本没问题后,再有意地升级固定版本号。 -
客户端侧缓存是合理的。 端点本身已通过
data_freshness_seconds缓存,但客户端可以在热点路径上再叠一层缓存。注意总的陈旧度(端点缓存 + 客户端缓存)。 -
限流按团队、按类别计算,而不是按端点。 调用非物化端点时,与所有其他查询流量共享团队级的 API 查询预算(约 240 次/分钟突发、2400 次/小时持续);物化端点则使用另一个更高、独立的共享桶(约 1200 次/分钟、12000 次/小时)。这里没有“按端点名”的限制,所以猛打一个端点会挤占同团队其他端点的配额。高流量调用方应尽量批量请求,并在 429 时退避。
以上限流数字在源码中有直接印证:
EndpointBurstThrottle对物化请求使用1200/minute、EndpointSustainedThrottle使用12000/hour,而非物化请求复用APIQueriesBurstThrottle/APIQueriesSustainedThrottle的共享桶(见 throttles.py)。物化/非物化的判定通过is_materialized_request在请求到达时动态解析(见 throttles.py)。 -
计费。 目前调用端点不收费,但一旦端点随托管数仓(managed warehouse)正式发布,将会纳入计费。如果用户计划高用量,提前提示这一点,避免未来成本出乎意料。
-
把缺失的东西反馈给 PostHog。 如果错误、限制或缺失能力阻碍了使用,请使用
agent-feedback工具——这是团队改进端点和这些工具的主要信号来源。
延伸阅读
- 创建与管理端点的完整指南:creating-an-endpoint/SKILL.md
- 端点版本管理与固定版本策略:managing-endpoint-versions/SKILL.md
- 排查端点性能问题:diagnosing-endpoint-performance/SKILL.md
- 端点执行日志排查:exploring-endpoint-execution-logs/SKILL.md
- 端点的核心 HTTP 实现:presentation/views/api.py
- 端点限流实现与速率常量:presentation/throttles.py