PostHog 端点在客户端代码中的消费指南鉴权、变量载荷、类型化客户端与限流处理【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/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:readscope写入类工具如endpoint-create、endpoint-update、endpoint-delete则要求endpoint:write这与下文“鉴权”一节的要求一致。端点 URL 的完整形态/api/projects/{team_id}/endpoints/{name}/runteam_id项目 ID数字。可在 PostHog 的项目设置中查看若用户不知道可通过projects-get获取。name端点名称不确定时可用endpoints-get-all列出全部端点。结尾的/run是必需的。在源码中端点路由注册于项目级路由之下见 routes.pyrouters.projects.register(rendpoints, EndpointViewSet, project_endpoints, [team_id])而run是EndpointViewSet上的一个 detail action见 api.py 的action(methods[GET, POST], detailTrue)因此 URL 形态与上文的/{name}/run完全吻合。方法选择POST 优先POST是规范方法GET在无请求体的简单场景下也可用但优先使用POST——变量放在请求体中。从源码看runaction 同时声明了GET和POST两种方法但limit、offset、version等参数既可从 body 读取也可从 query 读取见 api.py而variables等复杂载荷只存在于 body。鉴权个人 API Key 与服务端-only 原则端点使用**个人 API Keypersonal API key**进行认证请求头格式为Authorization: Bearer keyKey 是有作用域scoped的——对于端点Key 至少需要endpoint:read权限。错误排查口诀收到403通常缺少 scope或端点在另一个项目里收到401Key 缺失或格式错误。从源码看EndpointViewSet的scope_object endpoint而run在内的读取类 action 全部挂在scope_object_read_actions列表中见 api.py即endpoint:readscope 即可覆盖执行run与查看类操作。安全红线绝不要把个人 API Key 放进面向终端用户的客户端代码移动 App、浏览器 JS。个人 API Key 授予的是带作用域的账户级访问权限。面向客户的应用应当经由用户自己的后端转发请求由后端保管 Key。补充一点源码层面的细节run是公开的执行 API认证上仍要求登录、endpoint:readscope 与项目成员身份但会跳过资源级访问控制仅保留对象级单个端点的显式拒绝逻辑见 api.py。项目级 Secret API KeyPSAK只允许用于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_nameHogQL 端点对于带 breakdown 的 Insight 端点键为breakdown 属性名limit返回的最大行数offset跳过的行数仅 HogQL 端点支持refreshcache缓存足够新鲜时直接返回缓存结果、force总是重新计算、direct绕过物化直接查原始数据仅物化端点可用。默认cache调用endpoint-get可查看确切的变量形态响应中包含带声明变量的查询定义每个变量的code_name就是客户端应发送的键。这与 MCP 工具endpoint-run的参数覆盖说明一致见 tools.yamlHogQL 端点按code_name传参如{event_name: $pageview}带 breakdown 的 Insight 端点则用 breakdown 属性名作为键。另外注意请求体中的version字段或?versionN查询参数可用于指定调用某个端点版本body 优先于 query 参数见 api.py 的_parse_version_param。源码对参数还有额外校验limit最小为 1offset最小为 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_specaction路由为openapi.json支持?versionN为指定版本生成规范见 api.py。拿到 spec 后喂给代码生成器语言工具命令形态TypeScripthey-api/openapi-tsopenapi-ts -i spec.json -o ./generatedTypeScriptopenapi-generator-cliopenapi-generator-cli generate -i spec.json -g typescript-fetch -o ./generatedPythonopenapi-generator-cliopenapi-generator-cli generate -i spec.json -g python -o ./generatedGooapi-codegenoapi-codegen -packageclient 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告诉客户端实际运行的是哪个版本——这对日志记录、以及用?versionN固定到已知版本都很有用。对于 Insight 端点响应形态取决于查询类型TrendsQuery、LifecycleQuery、RetentionQuery——OpenAPI 规范会捕获当前版本的正确形态。无法物化的 Insight 类型如FunnelsQuery仍然返回其内联inline结果形态。从 PostHog CLI 调用端点本地测试、脚本或 CI 场景下仓库自带的posthog-cli可以直接调用端点无需手写 HTTPposthog-cli exp endpoints run—— 执行端点基于本地 YAML 定义posthog-cli exp endpoints {list,get,pull,push,diff}—— 查看端点或将端点作为 YAML 文件纳入版本管理GitOps 风格。CLI 命令的实现见 cli/src/commands.rsendpoints_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配置。注意这些命令位于expexperimental命名空间下API 可能变化。需要处理的错误响应状态码触发场景处理方式400物化端点缺少必需变量或变量类型非法展示错误消息修正调用401个人 API Key 缺失 / 错误检查 Authorization 头403Key 缺少endpoint:readscope或端点在另一个项目中调整 Key 的 scope404端点名拼写错误或端点未激活确认名称检查is_active429触发限流——限额按团队而非按端点见下方说明指数退避重试客户端尽可能缓存响应5xx查询执行失败ClickHouse 错误、超时等带退避重试持续失败则移交diagnosing-endpoint-performance处理从源码看run中版本号不存在会返回带current_version的 404api.pyoffset缺limit会返回 400非法数值参数同样返回 400 并记录 rejected run 日志。完整工作流确认端点名称。不知道的话可用execute-sql查询system.data_modeling_endpoints表或使用endpoints-get-all。用endpoint-get查看完整形态变量、物化状态、查询类型。确定鉴权姿态个人 API Key 放在服务端绝不放在客户端。若用户需要生成类型调用endpoint-openapi-spec把 spec 交给用户并按语言推荐生成器。根据变量声明构造一个示例请求载荷并走一遍测试调用。可选用本技能的endpoint-run实时确认载荷可用。收尾时交代处理要点物化变量规则、限流形态、用?versionN固定版本。实战示例从 Node.js 后端调用物化端点用户我想从我的 Node.js 后端调用 monthly_active_users能帮我接线并带上类型吗 Agent 步骤 - endpoint-get monthly_active_users → HogQL变量lookback_days int默认 30、org_idstring无默认值、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”。始终用?versionN调用。不带版本参数时会运行最新激活版本因此未来一次查询编辑会切出新版本可能悄然改变调用方的结果。在验证新版本没问题后再有意地升级固定版本号。客户端侧缓存是合理的。端点本身已通过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【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考