LightUp 第三方 API 契約已定案・端點已上線 v1.0.0 · 707394544381

報表數字(預覽)

狀態:預覽(preview),2026-11-06 加入。 契約已定案、可以呼叫,但尚未適用正式版的支援與棄用保證:欄位、錯誤細節與行為在轉為 ga 之前仍可能調整,調整會照版本與棄用公告。

讓租戶的機器帳號讀取自己的報表數字,例如每日的流量與結帳成效。這些數字和後台報表頁看到的相同。

能力 操作 作用
lightup.analytics.traffic.read GET /v1/analytics/traffic/query 讀取一個指標
lightup.analytics.traffic.read GET /v1/analytics/traffic/metrics 列出可用的指標

目前只開放流量與結帳漏斗的次數(工作階段、頁面、加購、結帳與付款的次數),不含金額。依渠道的訂單與營收屬於營收報表;營收、廣告與其他領域的報表能力還在規劃中,見能力目錄。

範圍與授權

查詢

GET /v1/analytics/traffic/query?topic=traffic&metric=channels&granularity=day&start=2026-11-05&end=2026-11-12

start 含、end 不含,都是租戶時區的日期。先呼叫 GET /v1/analytics/traffic/metrics,可以知道有哪些指標、每個指標支援哪些粒度。

回應的 meta.notes 寫著這批數字的限制,例如資料從哪一天開始才有,請一併讀取。meta.isPartial 為 true 表示有部分資料讀取失敗,數字可能偏低。

限制

項目 上限 超過時
範圍 最長 400 天;day 粒度最長 92 天 422 schema_invalid
列數 每次最多 5,000 列 422 schema_invalid,請縮小範圍

請把用量控制在同時 2 個查詢、每分鐘 30 次以內。 超過時會收到 429 rate_limited 並帶 Retry-After。這是你可以放心使用的範圍,不是精確的上限:實際開始拒絕的時間點可能稍晚,請不要依賴它。

一次查詢約需 0.2–2 秒,太久會回 503,可以依 Retry-After 重試。這組操作是給每日報表用的,不適合輪詢。