consuming-endpoints-from-client-code

从客户端代码调用端点

此技能是 creating-an-endpoint 的调用方对应技能。它可帮助你将现有端点集成到独立代码库中，例如移动应用、服务器后端、客户仪表板或下游流水线。此处不会修改任何 PostHog 代码。

何时使用此技能

• “如何调用我的端点？”／“请求格式是什么样的？”
• “为此端点生成一个类型化的 TypeScript／Python／Go 客户端”
• “调用端点时出现 401”／身份验证相关问题
• “省略 user_id 时端点会拒绝我的调用” → 关于物化端点变量的问题
• “如何处理速率限制？”

如果用户要创建端点，请先使用 creating-an-endpoint。

可用工具

工具	用途
endpoint-get	获取指定端点的完整配置，包括查询结构和必需变量
endpoint-openapi-spec	获取单个端点的 OpenAPI 3.0 规范，可直接交给代码生成器
endpoint-run	对端点进行实时调用 — 可用于在将载荷提供给用户的应用之前确认其是否有效

端点 URL

/api/projects/{team_id}/endpoints/{name}/run

• team_id 是项目 ID（数字）。可在 PostHog 的项目设置中找到；如果用户不知道，也可通过 projects-get 获取。
• name 是端点名称 — 如果用户不确定，可查看 endpoints-get-all。
• 末尾的 /run 是必需的。

POST 是标准方法。对于不带请求正文的简单情况，GET 也可用，但优先使用 POST — 变量应放在正文中。

身份验证

端点使用个人 API 密钥进行身份验证。请求头如下：

Authorization: Bearer <key>

密钥具有作用域 — 对于端点，密钥至少需要 endpoint:read。如果用户收到 403，通常是缺少所需作用域；如果收到 401，则说明密钥缺失或格式错误。

切勿将个人 API 密钥放入要交付给最终用户的客户端代码中（移动应用、浏览器 JS）。个人 API 密钥授予对账户的特定作用域访问权限。对于面向客户的应用，应通过用户自己的后端进行请求，并由该后端保存密钥。

请求载荷

{
  "variables": { "code_name_1": value, "code_name_2": value },
  "limit": 100,
  "offset": 0,
  "refresh": "cache"
}

字段	说明
variables	HogQL 端点按 code_name 作为键；对于带有分组的洞察端点，键为分组属性名称
limit	返回的最大行数。
offset	跳过的行数。仅适用于 HogQL 端点
refresh	"cache"（如果缓存结果足够新鲜，则返回缓存结果）、"force"（始终重新计算）、"direct"（绕过物化，仅适用于物化端点）。默认值为 "cache"

调用 endpoint-get 查看确切的变量结构。响应包含带有已声明变量的查询定义 — 客户端应发送每个变量的 code_name。

物化端点：所有变量都是必需的

如果 endpoint-get 在当前版本中显示 is_materialized: true，则每次调用端点时都必须传入 所有已声明的变量。这是安全边界——如果没有筛选条件，单次调用就会返回整个预聚合数据集。

常见症状：用户的应用在端点未物化时可以正常工作，但启用物化后开始返回 400 错误。错误消息会列出缺少的变量。

物化端点不支持可选变量或部分变量，这是一个已知限制，PostHog 团队计划解除该限制。如果必须提供所有变量会阻碍用户的使用场景，请通过 agent-feedback 工具发送反馈——团队会根据这类需求信号确定优先级。

生成类型化客户端

端点通过 endpoint-openapi-spec 提供自己的 OpenAPI 3.0 规范。将其输入代码生成器：

语言	工具	命令形式
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

生成的客户端会为用户提供变量负载和响应结构的类型定义。当端点的查询发生变化时，请重新生成（每个新版本的变量可能不同）。

如果用户有多个端点，可以为每个端点生成一个规范并将其合并，也可以为每个端点分别生成一个客户端并同时使用。

响应结构

典型的成功响应：

{
  "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 固定到已知版本。

对于洞察端点，响应结构取决于查询类型（TrendsQuery、 LifecycleQuery、RetentionQuery）——OpenAPI 规范会反映当前版本对应的结构。无法物化的洞察类型（例如 FunnelsQuery）仍会返回其内联结果结构。

通过 PostHog CLI 调用

对于本地测试、脚本或 CI，仓库中的 posthog-cli 可以调用端点，无需手动编写 HTTP 请求：

• posthog-cli exp endpoints run — 执行一个端点（使用本地 YAML 定义）
• posthog-cli exp endpoints {list,get,pull,push,diff} — 检查端点，或在版本控制中以 YAML 文件的形式管理端点（GitOps 风格）

身份验证使用相同的个人 API 密钥，可通过 posthog-cli login 或 POSTHOG_CLI_API_KEY / POSTHOG_CLI_PROJECT_ID / POSTHOG_CLI_HOST 环境变量设置。（这些功能位于 exp 下，属于实验性功能，可能会发生变化。）

需要处理的错误响应

状态	发生时机	处理方式
400	物化端点缺少必需变量，或变量类型无效	显示错误消息；修正调用
401	缺少个人 API 密钥，或密钥错误	检查 Authorization 标头
403	密钥缺少 endpoint:read 范围，或端点属于其他项目	调整密钥范围
404	端点名称拼写错误，或端点未激活	确认名称；检查 is_active
429	请求受到速率限制 — 限制针对团队，而非单个端点（见下方说明）	指数退避；尽可能在客户端缓存响应
5xx	查询执行失败（ClickHouse 错误、超时等）	退避后重试。如果问题持续存在，交由 diagnosing-endpoint-performance 处理

工作流

1. 确认端点名称。如果未知，使用 execute-sql 查询 system.data_modeling_endpoints 列出端点（或使用 endpoints-get-all）。
2. 使用 endpoint-get 查看完整结构：变量、物化状态和查询类型。
3. 确定身份验证方式：在服务器上使用个人 API 密钥，切勿在客户端使用。
4. 如果用户需要生成的类型，调用 endpoint-openapi-spec，将规范交给用户，并 推荐适用于其语言的生成器。
5. 根据变量声明构建示例请求负载，并演示测试调用。
6. 可以选择从此技能调用 endpoint-run，确认负载有效。
7. 最后说明处理注意事项：物化变量规则、速率限制形式，以及使用 ?version=N 固定到某个版本。

示例交互

User: "I want to call monthly_active_users from my Node.js backend.
       Can you help me wire it up with types?"

Agent steps:
- endpoint-get monthly_active_users → HogQL, variables: lookback_days
  (int, default 30), org_id (string, no default), is_materialized: true
- "Two things to know upfront:
   1. This endpoint is materialised, so both lookback_days and org_id
      must be passed on every call. Calls without them will be rejected.
   2. You'll need a personal API key with endpoint:read scope. Set it
      as PH_API_KEY in your server env — never ship it in client code."

- endpoint-openapi-spec monthly_active_users → returns spec

- "Here's the spec. Drop it in your repo and run:
     pnpm dlx @hey-api/openapi-ts -i spec.json -o ./generated/posthog
   That gives you typed client functions.

   A minimum call looks like:
     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 } }

   The response includes columns and rows — your client will pick that
   up from the generated types.

   Want me to do a sample call to verify the payload works?"

重要说明

• 个人 API 密钥仅限在服务端使用。 切勿将其放入移动应用或浏览器 JS 中。
• 查询发生变化时，请重新生成客户端。 每个新版本的端点都可能新增或移除变量 — 重新获取规范以保持类型同步。
• 物化端点会拒绝缺少变量的调用。 这是有意为之。如果用户在启用物化后报告 400 错误，问题出在调用中，而不是端点。
• 固定到某个版本 — 不要依赖“latest”。 始终使用 ?version=N 调用。不带该参数时会运行最新的活动版本，因此未来编辑查询（会创建新版本）可能悄然改变调用方的结果。验证新版本后，再有意更新固定的版本号。
• 客户端缓存完全可行。 端点已通过 data_freshness_seconds 进行缓存，但客户端可以针对高频路径再叠加一层缓存。请留意总陈旧时间（端点缓存 + 客户端缓存）。
• 速率限制按团队和类别计算 — 而非按端点计算。 对非物化端点的调用与所有其他查询流量共用团队级 API 查询额度（突发约 240 次/分钟，持续约 2400 次/小时）；物化端点使用另一个更高的共享额度（约 1200 次/分钟，约 12000 次/小时）。没有按端点名称设置的限制，因此，对单个端点发起大量调用可能会影响同一团队的其他端点。高负载调用方应尽可能批量处理，并在收到 429 时退避。
• 定价。 目前调用端点不收费，但端点与托管数据仓库一同推出后将开始收费。如果用户计划大量使用，请提前告知，以免未来的费用令人意外。
• 告诉 PostHog 哪些功能尚有欠缺。 如果错误、限制或缺少某项能力造成阻碍，请使用 agent-feedback 工具 — 团队主要依靠它来改进端点和这些工具。