分析查询 API 允许您在一个日期范围内查询聚合的体验指标。此 API 支持：
- 查询每日活跃用户 (DAU)、收入、留存和您体验的其他指标。
- 按平台、国家和年龄组等维度过滤和分组结果。
- 自动将慢查询处理为长期运行的操作，您可以轮询以获取结果。
在使用此 API 之前，您必须为您的体验生成 API 密钥。创建密钥时，将您的体验添加到 访问权限 并授予它对 universe.analytics:read 操作的访问权限，属于 universe-analytics 系统。在每个请求的 x-api-key 请求头中包含该密钥。
所有端点都使用您的宇宙 ID，您可以在创作者仪表板中找到，通过选择您的体验并从概览页面复制 宇宙 ID。
查询指标
要查询您的体验的指标：
- 将 API 密钥复制到 x-api-key 请求头中。
- 将 URL 中的 ${UniverseId} 替换为您体验的宇宙 ID。
- 将 metric 设置为您想要查询的指标，例如 DailyActiveUsers。
- 将 startTime 和 endTime 设置为您想要的日期范围，使用 RFC 3339 UTC 时间戳。
- 发送请求。
查询每日活跃用户
大多数查询会立即完成并返回 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。请参见 长期运行的操作。
请求体字段
| 字段 | 类型 | 必需 | 描述 |
|---|---|---|---|
| metric | string | 是 | 要查询的指标。例如，DailyActiveUsers。完整列表请参见 支持的指标。 |
| granularity | string | 是 | 每个数据点的时间桶大小。请参见 粒度选项。 |
| startTime | string | 是 | 查询窗口的开始，以 RFC 3339 时间戳表示。包含。可接受任何 UTC 偏移；结果始终以 UTC 分桶。 |
| endTime | string | 是 | 查询窗口的结束，以 RFC 3339 时间戳表示。不包含。例如，"2026-02-01T00:00:00Z" 包括至 1 月 31 日的数据。 |
| breakdown | string[] | 否 | 按维度分组结果的维度。每个条目是一个单独的维度名称，例如 "Platform"。如果不需要细分，则省略。请参见 使用细分。 |
| filter | object[] | 否 | 过滤条件以缩小到特定维度值的结果。每个条目都有 dimension、values 和 operation。如果不需要过滤，则省略。请参见 过滤结果。 |
| limit | integer | 否 | 要返回的最大细分系列数，按总指标值降序排列。仅在 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 时，使用相同的 x-api-key 请求头发送 GET 请求到 https://apis.roblox.com/analytics-query-api/{path} — 用响应中的 path 值替换 {path}。重复此操作直到 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": "请求的粒度不支持此指标。"
}
}
| 字段 | 类型 | 描述 |
|---|---|---|
| path | string | 操作路径，与初始响应中返回的值匹配。 |
| done | boolean | 错误存在时始终为 true。 |
| metadata.createdTime | string | 操作创建的 RFC 3339 时间戳。 |
| error.code | integer | 数字错误代码。请参见 常见错误。 |
| error.message | string | 可读的错误描述。 |
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。
并非每个指标都支持每种粒度。有关详细信息，请参见 支持的指标。
| 粒度 | 描述 | 备注 |
|---|---|---|
| OneMinute | 1 分钟桶 | 仅限性能指标。 |
| HalfHour | 30 分钟桶 | 仅限性能指标。 |
| OneHour | 1 小时桶 | 性能指标，以及一些货币化和推荐事件指标。 |
| OneDay | 1 天桶 | 所有指标均支持。 |
| OneWeek | 1 周桶 | 大多数参与度、货币化和获取指标。 |
| OneMonth | 1 个月桶 | 大多数参与度、货币化和获取指标。 |
| None | 整个范围的单一数据点 | 大多数参与度、货币化和获取指标。 |
超过两年的日期范围仅支持 OneWeek、OneMonth 或 None。
使用细分
并非每个指标都支持每个细分。有关每个指标可用的细分，请参见 支持的指标。
细分按维度分组指标结果，每个唯一的维度值返回一个系列。向请求中添加一个包含一个或多个维度名称的 breakdown 数组。
按平台细分的收入查询
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 | 维度名称，匹配请求字段中的条目。 |
| value | 原始维度值。在构建 filter 查询时使用。 |
| displayValue | 维度值的可读标签。当不存在显示标签时省略。对于像产品 ID 或漏斗步骤名称这样的维度，可能与 value 不同。 |
过滤结果
过滤器将查询结果缩小到特定的维度值。将 filter 数组添加到请求中，每个条目指定一个 dimension、要匹配的 values 和要应用的 operation。
仅查询移动设备的 DAU
过滤操作
| 操作 | 描述 |
|---|---|
| In | 包含维度值在提供的集合中的结果。 |
| NotIn | 排除维度值在提供的集合中的结果。 |
| GreaterThan | 包含数字维度值大于提供值的结果。 |
| GreaterThanOrEqual | 包含数字维度值大于或等于提供值的结果。 |
| LessThan | 包含数字维度值小于提供值的结果。 |
| LessThanOrEqual | 包含数字维度值小于或等于提供值的结果。 |
| Match | 包含维度值与提供字符串模式匹配的结果。 |
您可以将过滤器与细分组合在同一请求中。
发现维度值
维度值端点列出了一个或多个指标的维度在一个日期范围内的可用值，而不计算指标本身。使用它来发现有效的 filter 和 breakdown 查询值——例如，国家、产品 ID 或漏斗步骤 ID。
要查询您的体验的维度值：
- 将 API 密钥复制到 x-api-key 请求头中。
- 将 URL 中的 ${UniverseId} 替换为您体验的宇宙 ID。
- 将 metric 设置为为维度提供上下文的指标。
- 将 dimensions 设置为您想要值的维度名称。
- 将 startTime 和 endTime 设置为您想要的日期范围，使用 RFC 3339 UTC 时间戳。
- 发送请求。
发现 DAU 的国家值
请求体字段
| 字段 | 类型 | 必需 | 描述 |
|---|---|---|---|
| metric | string | 是 | 要解析其维度的指标。为维度查找提供命名空间上下文。 |
| dimensions | string[] | 是 | 要检索值的维度名称。每个条目是一个单独的维度名称，例如 "Country"。 |
| startTime | string | 是 | 查询窗口的开始，以 RFC 3339 时间戳表示。包含。可接受任何 UTC 偏移；结果始终以 UTC 分桶。 |
| endTime | string | 是 | 查询窗口的结束，以 RFC 3339 时间戳表示。不包含。例如，"2026-02-01T00:00:00Z" 包括至 1 月 31 日的数据。 |
| filter | object[] | 否 | 过滤器以缩小结果到特定的维度值。每个条目都有 dimension、values 和 operation。如果不需要过滤，则省略。请参见 过滤结果。 |
| granularity | string | 否 | 时间桶大小。与指标端点不同，此字段是可选的。请参见 粒度选项。 |
| limit | integer | 否 | 每个维度返回的最大值，按总指标值降序排名。仅在省略 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）存在时出现。对于大多数维度省略，包括 Country。 可能与 value 不同，例如产品 ID 或漏斗步骤名称。 |
错误会使用与指标端点相同的 done: true 和 error 信封。对指定维度不支持的请求返回 400，代码为 2001。请参见 常见错误。
常见查询
以下示例展示常见查询，包括可在创作者仪表板分析页面上找到的指标。
收入
查询每日收入（Robux）
D1 留存率
查询 D1 留存率
新用户与回归用户
查询 DAU，分为新用户与回归用户
每周聚合
使用更粗的粒度查看更长期限，数据点较少。在 OneWeek 粒度下，每个桶计算七天内的独立用户数，而不是每日值的总和。
以每周粒度查询 DAU
前 N 名细分
要按一个指标排名并为同一组值显示另一个指标，请使用两个请求。例如，要查看按 DAU 排名前 5 个国家的付费用户转化率：
步骤 1: 发现前 N 个维度值。使用 granularity: "None" 获取单个聚合结果并使用 limit 限制返回的系列数：
发现按 DAU 排名前 5 个国家
步骤 2: 查询显示指标，过滤步骤 1 返回的值：
前 5 个国家的付费用户转化率
漏斗步骤
漏斗显示用户在您的体验中通过定义步骤序列的进展。查询漏斗指标需要两个请求，因为步骤 ID 是动态的。
步骤 1: 发现漏斗步骤。当至少一个用户到达该步骤时，漏斗步骤才会出现在结果中。使用更长的回顾（90 天是安全默认）确保不经常到达的步骤仍然出现在发现响应中。使用 granularity: "None" 获取每个步骤的单个聚合结果：
发现 Levels 漏斗的漏斗步骤
步骤 2: 为每个步骤查询漏斗指标，过滤步骤 1 返回的步骤 ID：
Levels 漏斗每个步骤的用户流失率
常见错误
大多数错误被作为查询操作失败返回：响应主体包括 "done": true 和一个 error 对象，具有数字 code 和 message 字符串。身份验证和资源错误（401，404）是普通 HTTP 响应，没有主体信封，这就是表中 — 显示其错误代码的原因。
| 状态 | 代码 | 原因 | 解决方案 |
|---|---|---|---|
| 400 | 2001 | 缺少必需字段或字段值无效（例如，不被识别的 metric 或 granularity）。 | 检查 请求体字段 表，并确认所有值拼写正确。 |
| 400 | 2001 | 请求的粒度不支持指定的指标或日期范围。 | 请参见 粒度选项。对于超过两年的日期范围，使用 OneWeek、OneMonth 或 None。 |
| 400 | 2001 | filter 或 breakdown 中的一个维度不支持指定的指标。 | 请参见 支持的指标。 |
| 400 | 2001 | startTime 超过该指标的数据保留期。 | 标准指标保留数据最长可达四年。性能指标最长保留 28 天。 |
| 401 | — | x-api-key 请求头缺失、无效或被撤销，或者密钥对此宇宙没有宇宙分析权限。 | 验证密钥值并确认 API 密钥在创作者仪表板上具有正确的权限。 |
| 404 | — | 操作 ID 不存在。 | 确认初始响应中返回的操作 ID，并验证宇宙 ID 是否正确。 |
| 429 | 3000 | 查询超出了数据点预算。 | 减少日期范围，使用更粗的粒度，或使用 limit 减少细分系列数。 |
| 500 | 2000 | 发生意外的服务器错误。 | 重试请求。如果错误持续，创建一个新的 DevForum 帖子。 |
| 503 | 2002 | 发生瞬时故障。 | 稍后重试请求。 |
| 504 | 1000 | 查询在最大重试次数后超时。 | 尝试更短的日期范围、较少的细分或较粗的粒度。 |