創作者

分析

*此內容是使用 AI（Beta 測試版）翻譯，可能含有錯誤。若要以英文檢視此頁面，請按一下這裡。

分析查詢 API 讓您可以在一段日期範圍內查詢彙總的體驗度量指標。該 API 支持：

  • 查詢您的體驗的每日活躍用戶（DAU）、收入、留存率和其他指標。
  • 根據平台、國家和年齡組等維度過濾和分組結果。
  • 自動處理長時間運行的查詢，將其視為長期操作，您可以輪詢其結果。

在使用此 API 之前，您必須為您的體驗生成一個 API 密鑰。在創建密鑰時，將您的體驗添加到 訪問權限 並授予其對 universe.analytics:read 操作的訪問權限。每次請求時，請在 x-api-key 請求標頭中包含該密鑰。

所有端點都使用您的宇宙 ID，您可以在創作者儀表板上通過選擇您的體驗並從概述頁面複製 宇宙 ID 來找到它。

查詢指標

要查詢您的體驗的指標：

  1. 將 API 密鑰複製到 x-api-key 請求標頭中。
  2. 用您的體驗的宇宙 ID 替換 URL 中的 ${UniverseId}。
  3. 將 metric 設置為您要查詢的指標，例如 DailyActiveUsers。
  4. 將 granularity 設置為支持的時間區間大小，例如 OneDay。請參見粒度選項。
  5. 將 startTime 和 endTime 設置為您希望的日期範圍，使用 RFC 3339 UTC 時間戳。
  6. 發送請求。
查詢每日活躍用戶
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \

--header 'x-api-key: ${ApiKey}' \

--header 'Content-Type: application/json' \

--data '{

    "metric": "DailyActiveUsers",

    "granularity": "OneDay",

    "startTime": "2026-01-01T00:00:00Z",

    "endTime": "2026-02-01T00:00:00Z"

}'

大多數查詢立即完成並返回 200 OK：

回應 (200 OK)
{

  "path": "v1/universes/1234567890/operations/metrics/abc123",

  "done": true,

  "metadata": {

    "createdTime": "2026-01-15T00:00:00Z"

  },

  "response": {

    "values": [

      {

        "breakdowns": [],

        "dataPoints": [

          { "time": "2026-01-01T00:00:00Z", "value": 10000 },

          { "time": "2026-01-02T00:00:00Z", "value": 10500 }

        ]

      }

    ]

  }

}

對於大日期範圍，API 可能返回 202 Accepted，並且 "done": false。請參見長期運行的操作。

請求主體字段

字段類型必填描述
metricstring是要查詢的指標。例如 DailyActiveUsers。完整列表見支持的指標。
granularitystring是每個數據點的時間區間大小。請參見粒度選項。
startTimestring是查詢窗口的開始時間，作為 RFC 3339 時間戳。包括。任何 UTC 偏移都被接受；結果始終按 UTC 分組。
endTimestring是查詢窗口的結束時間，作為 RFC 3339 時間戳。不包括。例如，"2026-02-01T00:00:00Z" 包括到 1 月 31 日的數據。
breakdownstring[]否用於按維度分組結果的維度。每個條目是一個單一維度名稱，例如 "Platform"。如果不需要分解，則省略。請參見使用分解。
filterobject[]否用於將結果縮小到特定維度值的過濾器。每個條目都有 dimension、values 和 operation。如果不需要過濾，則省略。請參見過濾結果。
limitinteger否要返回的最多分解系列數，以總指標值降序排列。僅在 granularity 為 "None" 且 breakdown 設置時支持。省略該字段或將其設置為 0 將應用一個依賴於指標的默認限制。

您可以使用的最早 startTime 取決於指標類型：

  • 標準指標（參與度、營收、獲客、留存）：最多 4 年歷史。
  • 性能指標（崩潰率、幀率等）：最多 28 天歷史。

查詢超出保留期將返回 400 錯誤，代碼為 2001。

長期運行的操作

大多數查詢立即完成並返回 200 OK，其中 "done": true。對於日期範圍廣泛或許多分解系列的查詢，API 返回 202 Accepted，其中 "done": false 並提供一個 path 以供輪詢。

待定 (202):

{

  "path": "path/to/poll",

  "done": false,

  "metadata": {

    "createdTime": "2026-01-15T00:00:00Z"

  }

}

當 done 為 false 時，發送 GET 請求到 https://apis.roblox.com/analytics-query-api/{path} — 用回應中的 path 值替換 {path} — 並使用相同的 x-api-key 標頭。重複該過程直到 done 為 true。

完成 (200):

{

  "path": "path/to/poll",

  "done": true,

  "metadata": {

    "createdTime": "2026-01-15T00:00:00Z"

  },

  "response": {

    "values": [

      {

        "breakdowns": [],

        "dataPoints": [

          {

            "time": "2026-01-01T00:00:00Z",

            "value": 10000

          }

        ]

      }

    ]

  }

}

空的 breakdowns 陣列表示未請求分解。使用分解時，response.values 中的每個條目對應於一個維度值。請參見使用分解。

當操作失敗時，主體包含 error 而不是 response：

{

  "path": "path/to/poll",

  "done": true,

  "metadata": {

    "createdTime": "2026-01-15T00:00:00Z"

  },

  "error": {

    "code": 2001,

    "message": "請求的粒度不支持此指標。"

  }

}
字段類型描述
pathstring操作路徑，與初始回應中返回的值匹配。
doneboolean當存在錯誤時始終為 true。
metadata.createdTimestring操作創建時間的 RFC 3339 時間戳。
error.codeinteger數字錯誤代碼。請參見常見錯誤。
error.messagestring可讀的錯誤描述。

response.values 中的每個條目代表一個序列，每個維度值一個系列，當未請求分解時，則一個條目顯示為 breakdowns: []。dataPoints 中的每個數據點有：

字段描述
time時間區間開始的 UTC 時間戳。
value數字指標值。
stringValues數據點的文本值，作為字符串數組。僅對文本值的指標存在。請見下文的文本值指標。
status數據點的狀態指示器。在該系列沒有適用狀態時省略。請見下文的數據點狀態。

文本值指標

大多數指標是數字並在 value 中報告其結果。少數指標則用文本描述每個數據點。對於這些，數據以 stringValues 陣列返回，並且 value 沒有意義。對於數字指標，stringValues 字段完全省略。

例如，ThumbnailWinningSegments 在每個時間區間上報告獲勝的縮略圖片段，作為字符串列表：

{

  "time": "2026-01-01T00:00:00Z",

  "value": 0,

  "stringValues": ["TopEngagement", "HighCTR"]

}

數據點狀態

狀態描述例子
Valid數據點是完整的，涵蓋整個時間區間。已確定的創作者獎勵支付。
Projected該值是估算的，可能會改變。尚未確定的期間預測的創作者獎勵支付。
NotStatisticallySignificant樣本大小不足以提供可靠值。小國家的崩潰率，可能會誤認為是真實回歸的嘈雜值。

粒度選項

granularity 字段控制回應中每個時間區間的大小。區間邊界對齊 UTC。例如，OneDay 區間從 UTC 午夜到 UTC 午夜，因此 startTime 或 endTime 中的任何 UTC 偏移在分組之前都會標準化為 UTC。

並非每個指標都支持每個粒度。請參見支持的指標以獲取詳細信息。

粒度描述備註
OneMinute1 分鐘區間僅限性能指標。
HalfHour30 分鐘區間僅限性能指標。
OneHour1 小時區間性能指標，以及某些營收和推薦事件指標。
OneDay1 天區間所有指標都支持。
OneWeek1 星期區間大多數參與度、營收和獲客指標。
OneMonth1 個月區間大多數參與度、營收和獲客指標。
None整個範圍的單一數據點大多數參與度、營收和獲客指標。

使用分解

並非每個指標都支持每個分解。請參見支持的指標，了解哪些分解可用於每個指標。

分解根據一個維度對指標結果進行分組，返回每個唯一維度值的一個系列。將 breakdown 陣列與一個或多個維度名稱添加到請求中。

查詢按平台分解的收入
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \

--header 'x-api-key: ${ApiKey}' \

--header 'Content-Type: application/json' \

--data '{

    "metric": "DailyRevenue",

    "granularity": "OneDay",

    "breakdown": ["Platform"],

    "startTime": "2026-01-01T00:00:00Z",

    "endTime": "2026-02-01T00:00:00Z"

}'

response.values 中的每個條目都包含一個 breakdowns 陣列，該陣列識別該系列的維度值：

{

  "response": {

    "values": [

      {

        "breakdowns": [{ "dimension": "Platform", "value": "Computer" }],

        "dataPoints": [{ "time": "2026-01-01T00:00:00Z", "value": 8200 }]

      },

      {

        "breakdowns": [{ "dimension": "Platform", "value": "Phone" }],

        "dataPoints": [{ "time": "2026-01-01T00:00:00Z", "value": 3400 }]

      }

    ]

  }

}

breakdowns 中的每個對象都有：

字段描述
dimension維度名稱，與 breakdown 請求字段中的條目匹配。
value原始維度值。使用此值構造 filter 查詢。
displayValue維度值的人可讀標籤。當沒有顯示標籤存在時省略。對於產品 ID 或漏斗步驟名稱等維度，可能與 value 不同。

過濾結果

過濾器將查詢結果縮小到特定維度值。將 filter 陣列添加到請求中，每個條目指定一個 dimension、要匹配的 values 和要應用的 operation。

僅查詢移動設備的 DAU
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \

--header 'x-api-key: ${ApiKey}' \

--header 'Content-Type: application/json' \

--data '{

    "metric": "DailyActiveUsers",

    "granularity": "OneDay",

    "filter": [

        {

            "dimension": "Platform",

            "values": ["Phone", "Tablet"],

            "operation": "In"

        }

    ],

    "startTime": "2026-01-01T00:00:00Z",

    "endTime": "2026-02-01T00:00:00Z"

}'

過濾操作

操作描述
In包括維度值在所提供集合中的結果。
NotIn排除維度值在所提供集合中的結果。
GreaterThan包括維度數值大於所提供值的結果。
GreaterThanOrEqual包括維度數值大於或等於所提供值的結果。
LessThan包括維度數值小於所提供值的結果。
LessThanOrEqual包括維度數值小於或等於所提供值的結果。
Match包括維度值與提供的字符串模式匹配的結果。

您可以在同一請求中將分解與過濾器結合使用。

探索維度值

維度值端點列出一段日期範圍內一個或多個指標的可用維度值，而不計算指標本身。使用它發現有效的 filter 和 breakdown 查詢值 — 例如，國家、產品 ID 或漏斗步驟 ID。

要查詢您體驗的維度值：

  1. 將 API 密鑰複製到 x-api-key 請求標頭中。
  2. 用您的體驗的宇宙 ID 替換 URL 中的 ${UniverseId}。
  3. 將 metric 設置為提供維度上下文的指標。
  4. 將 dimensions 設置為您希望獲取值的維度名稱。
  5. 將 startTime 和 endTime 設置為您希望的日期範圍，使用 RFC 3339 UTC 時間戳。
  6. 發送請求。
發現 DAU 的國家值
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/dimension-values' \

--header 'x-api-key: ${ApiKey}' \

--header 'Content-Type: application/json' \

--data '{

    "metric": "DailyActiveUsers",

    "dimensions": ["Country"],

    "startTime": "2026-01-01T00:00:00Z",

    "endTime": "2026-02-01T00:00:00Z"

}'

請求主體字段

字段類型必填描述
metricstring是需要解析其維度的指標。為維度查找提供命名空間上下文。
dimensionsstring[]是要檢索值的維度名稱。每個條目是一個單一維度名稱，例如 "Country"。
startTimestring是查詢窗口的開始時間，作為 RFC 3339 時間戳。包括。任何 UTC 偏移都是被接受的；結果始終按 UTC 分組。
endTimestring是查詢窗口的結束時間，作為 RFC 3339 時間戳。不包括。例如，"2026-02-01T00:00:00Z" 包括到 1 月 31 日的數據。
filterobject[]否用於將結果縮小到特定維度值的過濾器。每個條目都有 dimension、values 和 operation。如果不需要過濾，則省略。請參見過濾結果。
granularitystring否時間區間大小。與指標端點不同，這個字段是可選的。請參見粒度選項。
limitinteger否每個維度返回的最大值數，按總指標值降序排列。僅在省略 granularity 或使用 "None" 時支持。省略該字段或將其設置為 0 將應用一個依賴於指標的默認限制。

大多數查詢立即完成並返回 200 OK，其中 "done": true。對於日期範圍廣泛的查詢，API 返回 202 Accepted，具有 "done": false，並提供一個 path 以供輪詢。請參見長期運行的操作以獲取輪詢流程。輪詢時，使用回應中的 path 值 — 它指向 v1/universes/{universeId}/operations/dimension-values/{operationId}，與指標輪詢路徑不同。

完成 (200):

{

  "path": "path/to/poll",

  "done": true,

  "metadata": {

    "createdTime": "2026-01-15T00:00:00Z"

  },

  "response": {

    "values": [

      {

        "dimension": "Country",

        "values": [{ "value": "US" }, { "value": "GB" }]

      }

    ]

  }

}

response.values 中的每個條目代表一個請求的維度。values 中的每個對象都有：

字段描述
value原始維度值。使用此值構造 filter 查詢。
displayValue人體可讀的維度值標籤。僅對 ID 類維度（如產品 ID）存在。對於大多數維度，省略。對於像產品 ID 或漏斗步驟名稱等維度，value 與 displayValue 可能不同。

錯誤使用與指標端點相同的 done: true 和 error 封裝。不支持所指定指標的維度返回 400，代碼為 2001。請參見常見錯誤。

常見查詢

以下示例顯示常見查詢，包括在創作者儀表板分析頁面上可用的指標。

收入

查詢 Robux 的每日收入
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \

--header 'x-api-key: ${ApiKey}' \

--header 'Content-Type: application/json' \

--data '{

    "metric": "DailyRevenue",

    "granularity": "OneDay",

    "startTime": "2026-01-01T00:00:00Z",

    "endTime": "2026-02-01T00:00:00Z"

}'

D1 留存

查詢 D1 留存
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \

--header 'x-api-key: ${ApiKey}' \

--header 'Content-Type: application/json' \

--data '{

    "metric": "ForwardD1Retention",

    "granularity": "OneDay",

    "startTime": "2026-01-01T00:00:00Z",

    "endTime": "2026-02-01T00:00:00Z"

}'

新用戶與回訪用戶

查詢按新舊用戶分解的 DAU
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \

--header 'x-api-key: ${ApiKey}' \

--header 'Content-Type: application/json' \

--data '{

    "metric": "DailyActiveUsers",

    "granularity": "OneDay",

    "breakdown": ["IsNewUser"],

    "startTime": "2026-01-01T00:00:00Z",

    "endTime": "2026-02-01T00:00:00Z"

}'

每週聚合

使用更粗的粒度以更長的範圍查看較少的數據點。在 OneWeek 粒度下，每個區間計算整個七天期間的獨特用戶，而不是每日值的總和。

每週粒度查詢 DAU
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \

--header 'x-api-key: ${ApiKey}' \

--header 'Content-Type: application/json' \

--data '{

    "metric": "DailyActiveUsers",

    "granularity": "OneWeek",

    "startTime": "2026-01-01T00:00:00Z",

    "endTime": "2026-04-01T00:00:00Z"

}'

頂級 N 分解

要按一個指標排名並顯示同一組值的另一個指標，請使用兩個請求。例如，要查看按 DAU 排名的前 5 個國家的付費用戶轉化率：

步驟 1： 發現前 N 的維度值。對於單個彙總結果使用 granularity: "None"，並使用 limit 來限制返回的系列數量：

查詢前 5 個 DAU 的國家
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \

--header 'x-api-key: ${ApiKey}' \

--header 'Content-Type: application/json' \

--data '{

    "metric": "DailyActiveUsers",

    "granularity": "None",

    "breakdown": ["Country"],

    "startTime": "2026-01-01T00:00:00Z",

    "endTime": "2026-02-01T00:00:00Z",

    "limit": 5

}'

步驟 2： 查詢顯示度指標，並過濾為第 1 步中返回的值：

頂級 5 個國家的付費用戶轉化率
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \

--header 'x-api-key: ${ApiKey}' \

--header 'Content-Type: application/json' \

--data '{

    "metric": "PayingUsersCVR",

    "granularity": "OneDay",

    "breakdown": ["Country"],

    "filter": [

        {

            "dimension": "Country",

            "values": ["US", "GB", "PH", "VN", "DE"],

            "operation": "In"

        }

    ],

    "startTime": "2026-01-01T00:00:00Z",

    "endTime": "2026-02-01T00:00:00Z"

}'

漏斗步驟

漏斗顯示用戶如何通過您體驗中定義的步驟序列進行進展。查詢漏斗指標需要兩個請求，因為步驟 ID 是動態的。

步驟 1： 發現漏斗步驟。當至少一個用戶達到該步驟時，漏斗步驟才會在結果中出現。使用更長的回溯（90 天是安全的默認）確保不常見的步驟仍然出現在發現回應中。使用 granularity: "None" 獲得每步的單一彙總結果：

查詢等級漏斗的漏斗步驟
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \

--header 'x-api-key: ${ApiKey}' \

--header 'Content-Type: application/json' \

--data '{

    "metric": "FunnelUserTotalCount",

    "granularity": "None",

    "breakdown": ["FunnelStep"],

    "filter": [

        {

            "dimension": "FunnelName",

            "values": ["Levels"],

            "operation": "In"

        }

    ],

    "startTime": "2025-11-01T00:00:00Z",

    "endTime": "2026-02-01T00:00:00Z"

}'

步驟 2： 查詢每個步驟的漏斗指標，並過濾為第 1 步中返回的步驟 ID：

等級漏斗每步的用戶流失率
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \

--header 'x-api-key: ${ApiKey}' \

--header 'Content-Type: application/json' \

--data '{

    "metric": "FunnelUserChurnRate",

    "granularity": "None",

    "breakdown": ["FunnelStep"],

    "filter": [

        {

            "dimension": "FunnelStep",

            "values": ["1", "2", "3", "4", "5"],

            "operation": "In"

        },

        {

            "dimension": "FunnelName",

            "values": ["Levels"],

            "operation": "In"

        }

    ],

    "startTime": "2026-01-01T00:00:00Z",

    "endTime": "2026-02-01T00:00:00Z"

}'

常見錯誤

大多數錯誤作為查詢操作失敗返回：回應主體包含 "done": true 和一個包含數字 code 和 message 字符串的 error 對象。身份驗證和資源錯誤（401、404）是純 HTTP 回應，沒有主體封裝，這就是為什麼下表顯示其錯誤代碼為 — 。

狀態代碼原因解決方案
4002001缺少必要字段或字段值無效（例如，無法識別的 metric 或 granularity）。檢查請求主體字段表，並驗證所有值的拼寫是否正確。
4002001請求的粒度不支持所指定的指標或日期範圍。請見粒度選項。超過兩年的日期範圍，請使用 OneWeek、OneMonth 或 None。
4002001filter 或 breakdown 中的維度不支持所指定的指標。請見支持的指標。
4002001startTime 超過了該指標的數據保留期。標準指標最多保留數據四年。性能指標最多保留 28 天。
401—x-api-key 標頭缺失、無效或已撤銷，或該密鑰對該宇宙沒有宇宙分析權限。驗證密鑰值並確認 API 密鑰在創作者儀表板上具有正確的權限。
404—操作 ID 不存在。確認初始回應中返回的操作 ID，並驗證宇宙 ID 是否正確。
4293000查詢超過了數據點預算。縮小日期範圍，使用更粗的粒度，或使用 limit 減少分解系列的數量。
5002000發生了意外的服務器錯誤。重試請求。如果錯誤持續存在，請創建一個新的 DevForum 帖子。
5032002發生了瞬時故障。在短暫延遲後重試請求。
5041000查詢在最大重試次數後超時。嘗試縮短日期範圍、減少分解數或使用更粗的粒度。
©2026 Roblox Corporation、Roblox、Roblox 標誌及 Powering Imagination 是我們在美國及其他國家地區的部分註冊與未註冊商標。
條款·隱私權·無障礙功能·支援
中文(繁體)