跳到主要内容
版本：2.0.0

API 参考

身份验证​

请求需在 Authorization 头中携带 Bearer 令牌。无效密钥返回 401；权限不足返回 403。

写入事件​

POST /v1/atlas/events —— 每次请求最多 1,000 条事件。

请求

{
  "events": [
    {
      "name": "checkout_completed",
      "user_id": "usr_8f3a1c",
      "timestamp": "2026-07-15T14:32:00Z",
      "properties": { "order_id": "ord_29xk3", "revenue": 84.50, "currency": "USD", "items": 3 }
    }
  ]
}

响应 —— 202 Accepted

{ "accepted": 1, "rejected": 0, "batch_id": "batch_7f2e9a1c" }

批次中部分事件校验失败时，其余会正常写入，失败项单独返回：

{
  "accepted": 2,
  "rejected": 1,
  "batch_id": "batch_7f2e9a1c",
  "errors": [{ "index": 2, "code": "invalid_timestamp", "message": "timestamp is more than 24h in the past" }]
}

查询原始事件​

GET /v1/atlas/events

参数类型说明
user_idstring按单一身份过滤
namestring按单一事件名过滤
since / untilISO 8601时间范围（默认最近 24 小时）
limitinteger最大 100，默认 20
cursorstring上次响应中的 next_cursor

响应 —— 200 OK

{
  "data": [
    {
      "id": "evt_4k2p91xz",
      "name": "checkout_completed",
      "user_id": "usr_8f3a1c",
      "timestamp": "2026-07-15T14:32:00Z",
      "properties": { "revenue": 84.50, "currency": "USD", "items": 3 }
    }
  ],
  "next_cursor": "eyJvZmZzZXQiOjIwfQ==",
  "has_more": true
}

漏斗​

POST /v1/atlas/funnels 创建定义；GET /v1/atlas/funnels/:id 计算并返回当前结果。

{ "name": "Signup to purchase", "steps": ["signup_completed", "product_viewed", "checkout_completed"], "window": "7d" }
{
  "id": "fnl_9x2k3p",
  "name": "Signup to purchase",
  "steps": [
    { "name": "signup_completed", "count": 4200, "conversion_from_previous": 1.0 },
    { "name": "product_viewed", "count": 3110, "conversion_from_previous": 0.74 },
    { "name": "checkout_completed", "count": 892, "conversion_from_previous": 0.29 }
  ]
}

群组​

GET /v1/atlas/cohorts/:id —— 每次调用都会重新计算。

{ "id": "cht_3f8a2c", "name": "Active purchasers (30d)", "size": 1847, "last_computed": "2026-07-15T14:32:00Z" }

错误​

HTTP 状态码code含义
400invalid_event_schema缺少必填字段或类型错误
400invalid_timestamp时间戳超出 24 小时范围
401invalid_api_key密钥缺失、格式错误或已吊销
403insufficient_scope密钥有效但无此项目权限
413batch_too_large单次请求超过 1,000 条事件
429rate_limited请参考 Retry-After 头进行重试

速率限制​

写入接口（/events）每个密钥每分钟 600 次，查询接口每分钟 60 次。限制按密钥计算，而非按项目。

技术支持​

如对 Atlas 有任何疑问，请联系产品团队或访问社区论坛。