La API de Consulta de Analítica te permite consultar métricas de experiencia agregadas durante un rango de fechas. Esta API soporta:
- Consultar usuarios activos diarios (DAU), ingresos, retención y otras métricas para tu experiencia.
- Filtrar y agrupar resultados por dimensiones como plataforma, país y grupo de edad.
- Manejo automático de consultas lentas como operaciones de larga duración para las cuales puedes consultar resultados.
Antes de usar esta API, debes generar una clave de API para tu experiencia. Al crear la clave, añade tu experiencia en Permisos de Acceso y otórgale acceso a la operación universe.analytics:read dentro del sistema universe-analytics. Incluye la clave en el encabezado de la solicitud x-api-key en cada solicitud.
Todos los endpoints utilizan tu ID de universo, que puedes encontrar en el Tablero del Creador al seleccionar tu experiencia y copiar el ID de Universo de la página de resumen.
Consultar una métrica
Para consultar una métrica para tu experiencia:
- Copia la clave de API en el encabezado de la solicitud x-api-key.
- Reemplaza ${UniverseId} en la URL con el ID de universo de tu experiencia.
- Establece metric a la métrica que deseas consultar, como DailyActiveUsers.
- Establece granularity a un tamaño de grupo de tiempo soportado, como OneDay. Ve Opciones de Granularidad.
- Establece startTime y endTime al rango de fechas que deseas, usando marcas de tiempo UTC en RFC 3339.
- Envía la solicitud.
Consultar usuarios activos diarios
La mayoría de las consultas se completan inmediatamente y devuelven 200 OK:
Respuesta (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 }
]
}
]
}
}
Para rangos de fechas grandes, la API puede devolver 202 Accepted con "done": false. Ve Operaciones de Larga Duración.
Campos del cuerpo de solicitud
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| metric | string | Sí | La métrica a consultar. Por ejemplo, DailyActiveUsers. Para la lista completa, ve Métricas Soportadas. |
| granularity | string | Sí | El tamaño del grupo de tiempo para cada punto de datos. Ve Opciones de Granularidad. |
| startTime | string | Sí | Inicio de la ventana de consulta, como una marca de tiempo en RFC 3339. Inclusivo. Se acepta cualquier desplazamiento UTC; los resultados siempre se agrupan en UTC. |
| endTime | string | Sí | Fin de la ventana de consulta, como una marca de tiempo en RFC 3339. Exclusivo. Por ejemplo, "2026-02-01T00:00:00Z" incluye datos hasta el 31 de enero. |
| breakdown | string[] | No | Dimensiones para agrupar resultados. Cada entrada es un nombre de dimensión único, como "Platform". Omitir si no se requiere desglose. Ve Usar Desgloses. |
| filter | object[] | No | Filtros para reducir resultados a valores de dimensión específicos. Cada entrada tiene dimension, values y operation. Omitir si no se requiere filtrado. Ve Filtrar Resultados. |
| limit | integer | No | Máximo número de series de desglose a devolver, clasificado por el valor total de la métrica en orden descendente. Solo soportado cuando granularity es "None" y breakdown está establecido. Omitir este campo o establecerlo en 0 aplica un límite predeterminado basado en la métrica. |
La fecha más temprana de startTime que puedes usar depende del tipo de métrica:
- Métricas Estándar (compromiso, monetización, adquisición, retención): hasta 4 años de historial.
- Métricas de Rendimiento (tasa de fallos, tasa de cuadros, etc.): hasta 28 días de historial.
Consultar más allá del período de retención devuelve un error 400 con código 2001.
Operaciones de Larga Duración
La mayoría de las consultas se completan inmediatamente y devuelven 200 OK con "done": true. Para consultas con grandes rangos de fechas o muchas series de desglose, la API devuelve 202 Accepted con "done": false y un path para consultar.
Pendiente (202):
{
"path": "path/to/poll",
"done": false,
"metadata": {
"createdTime": "2026-01-15T00:00:00Z"
}
}
Cuando done es false, envía una solicitud GET a https://apis.roblox.com/analytics-query-api/{path} — reemplazando {path} con el valor de path de la respuesta — usando el mismo encabezado x-api-key. Repite hasta que done sea true.
Completado (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
}
]
}
]
}
}
Un array breakdowns vacío indica que no se solicitó desglose. Cuando se utiliza un desglose, cada entrada en response.values corresponde a un valor de dimensión. Ve Usar Desgloses.
Cuando la operación falla, el cuerpo contiene error en lugar de response:
{
"path": "path/to/poll",
"done": true,
"metadata": {
"createdTime": "2026-01-15T00:00:00Z"
},
"error": {
"code": 2001,
"message": "La granularidad solicitada no es soportada para esta métrica."
}
}
| Campo | Tipo | Descripción |
|---|---|---|
| path | string | La ruta de la operación, que coincide con el valor devuelto en la respuesta inicial. |
| done | boolean | Siempre true cuando hay un error presente. |
| metadata.createdTime | string | Marca de tiempo en RFC 3339 de cuando se creó la operación. |
| error.code | integer | Código de error numérico. Ve Errores Comunes. |
| error.message | string | Descripción legible por humanos del error. |
Cada entrada en response.values representa una serie, una por valor de dimensión cuando se utiliza un desglose, o una única entrada con breakdowns: [] cuando no se solicita un desglose. Cada punto de datos en dataPoints tiene:
| Campo | Descripción |
|---|---|
| time | Marca de tiempo UTC para el inicio del grupo de tiempo. |
| value | El valor numérico de la métrica. |
| stringValues | Valores de texto para el punto de datos, como un array de cadenas. Solo presente para métricas con valores de texto. Ve Métricas con Valores de Texto más abajo. |
| status | Indicador de estado para el punto de datos. Omitido cuando no aplica ningún estado para la serie. Ve Estado del Punto de Datos más abajo. |
Métricas con Valores de Texto
La mayoría de las métricas son numéricas y reportan su resultado en value. Algunas métricas describen cada punto de datos con texto en lugar de un número. Para estas, los datos se devuelven en un array stringValues y value no tiene significado. El campo stringValues se omite completamente para métricas numéricas.
Por ejemplo, ThumbnailWinningSegments reporta los segmentos de miniaturas ganadoras para cada grupo de tiempo como una lista de cadenas:
{
"time": "2026-01-01T00:00:00Z",
"value": 0,
"stringValues": ["TopEngagement", "HighCTR"]
}
Estado del Punto de Datos
| Estado | Descripción | Ejemplo |
|---|---|---|
| Valid | El punto de datos está completo y cubre todo el grupo de tiempo. | Pago finalizado de recompensas para creadores. |
| Projected | El valor es una estimación y puede cambiar. | Estimación de pago de recompensas para creadores para un período que no se ha finalizado aún. |
| NotStatisticallySignificant | El tamaño de la muestra es insuficiente para producir un valor fiable. | Tasa de fallos para un país pequeño donde un valor ruidoso podría confundirse con una regresión real. |
Opciones de Granularidad
El campo granularity controla el tamaño de cada grupo de tiempo en la respuesta. Los límites de los grupos están alineados a UTC. Por ejemplo, los grupos de OneDay van de medianoche UTC a medianoche UTC, por lo que cualquier desplazamiento UTC en startTime o endTime se normaliza a UTC antes de agrupar.
No todas las métricas soportan cada granularidad. Ve Métricas Soportadas para más detalles.
| Granularidad | Descripción | Notas |
|---|---|---|
| OneMinute | Grupos de 1 minuto | Solo métricas de rendimiento. |
| HalfHour | Grupos de 30 minutos | Solo métricas de rendimiento. |
| OneHour | Grupos de 1 hora | Métricas de rendimiento, además de algunas métricas de monetización y eventos recomendados. |
| OneDay | Grupos de 1 día | Soportado por todas las métricas. |
| OneWeek | Grupos de 1 semana | La mayoría de las métricas de compromiso, monetización y adquisición. |
| OneMonth | Grupos de 1 mes | La mayoría de las métricas de compromiso, monetización y adquisición. |
| None | Un único punto de datos para todo el rango | La mayoría de las métricas de compromiso, monetización y adquisición. |
Los rangos de fechas mayores a dos años solo soportan OneWeek, OneMonth o None.
Usar Desgloses
No todas las métricas soportan cada desglose. Ve Métricas Soportadas para saber qué desgloses están disponibles para cada métrica.
Los desgloses agrupan los resultados de la métrica por una dimensión, devolviendo una serie por cada valor único de dimensión. Añade un array breakdown con uno o más nombres de dimensión a tu solicitud.
Consultar ingresos desglosados por plataforma
Cada entrada en response.values incluye un array breakdowns que identifica el valor de la dimensión para esa serie:
{
"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 }]
}
]
}
}
Cada objeto en breakdowns tiene:
| Campo | Descripción |
|---|---|
| dimension | El nombre de la dimensión, que coincide con la entrada en el campo de solicitud breakdown. |
| value | El valor bruto de la dimensión. Úsalo al construir consultas filter. |
| displayValue | Una etiqueta legible por humanos para el valor de la dimensión. Omitido cuando no existe etiqueta de visualización. Puede diferir de value para dimensiones como IDs de productos o nombres de pasos del embudo. |
Filtrar Resultados
Los filtros reducen los resultados de la consulta a valores de dimensión específicos. Añade un array filter a tu solicitud, donde cada entrada especifica una dimension, los values a coincidir y la operation a aplicar.
Consultar DAU solo para dispositivos móviles
Operaciones de Filtrado
| Operación | Descripción |
|---|---|
| In | Incluir resultados donde el valor de la dimensión esté en el conjunto proporcionado. |
| NotIn | Excluir resultados donde el valor de la dimensión esté en el conjunto proporcionado. |
| GreaterThan | Incluir resultados donde el valor numérico de la dimensión sea mayor que el valor proporcionado. |
| GreaterThanOrEqual | Incluir resultados donde el valor numérico de la dimensión sea mayor o igual que el valor proporcionado. |
| LessThan | Incluir resultados donde el valor numérico de la dimensión sea menor que el valor proporcionado. |
| LessThanOrEqual | Incluir resultados donde el valor numérico de la dimensión sea menor o igual que el valor proporcionado. |
| Match | Incluir resultados donde el valor de la dimensión coincida con el patrón de cadena proporcionado. |
Puedes combinar filtros con desgloses en la misma solicitud.
Descubrir Valores de Dimensión
El endpoint de valores de dimensión enumera los valores disponibles para una o más dimensiones de una métrica durante un rango de fechas, sin calcular la métrica en sí. Úsalo para descubrir valores válidos para consultas filter y breakdown, por ejemplo, países, IDs de productos o IDs de pasos del embudo.
Para consultar valores de dimensión para tu experiencia:
- Copia la clave de API en el encabezado de la solicitud x-api-key.
- Reemplaza ${UniverseId} en la URL con el ID de universo de tu experiencia.
- Establece metric a la métrica que proporciona contexto para las dimensiones.
- Establece dimensions a los nombres de las dimensiones para las que deseas valores.
- Establece startTime y endTime al rango de fechas que deseas, usando marcas de tiempo UTC en RFC 3339.
- Envía la solicitud.
Descubrir valores de país para DAU
Campos del Cuerpo de Solicitud
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| metric | string | Sí | La métrica cuyas dimensiones se deben resolver. Proporciona contexto de espacio de nombres para la búsqueda de dimensiones. |
| dimensions | string[] | Sí | Los nombres de dimensiones para los cuales recuperar valores. Cada entrada es un nombre de dimensión único, como "Country". |
| startTime | string | Sí | Inicio de la ventana de consulta, como una marca de tiempo en RFC 3339. Inclusivo. Cualquier desplazamiento UTC es aceptado; los resultados son siempre agrupados en UTC. |
| endTime | string | Sí | Fin de la ventana de consulta, como una marca de tiempo en RFC 3339. Exclusivo. Por ejemplo, "2026-02-01T00:00:00Z" incluye datos hasta el 31 de enero. |
| filter | object[] | No | Filtros para reducir resultados a valores de dimensión específicos. Cada entrada tiene dimension, values, y operation. Omitir para no filtrar. Ve Filtrar Resultados. |
| granularity | string | No | El tamaño del grupo de tiempo. A diferencia del endpoint de métricas, este campo es opcional. Ve Opciones de Granularidad. |
| limit | integer | No | Máximo número de valores para devolver por dimensión, clasificado por el valor total de la métrica en orden descendente. Solo soportado cuando granularity está omitido o es "None". Omitir este campo o establecerlo en 0 aplica un límite predeterminado basado en la métrica. |
La mayoría de las consultas se completan inmediatamente y devuelven 200 OK con "done": true. Para consultas con grandes rangos de fechas, la API devuelve 202 Accepted con "done": false y un path para consultar. Ve Operaciones de Larga Duración para el flujo de consulta. Al consultar, usa el valor path de la respuesta — apunta a v1/universes/{universeId}/operations/dimension-values/{operationId}, distinto de la ruta de consulta de métricas.
Completado (200):
{
"path": "path/to/poll",
"done": true,
"metadata": {
"createdTime": "2026-01-15T00:00:00Z"
},
"response": {
"values": [
{
"dimension": "Country",
"values": [{ "value": "US" }, { "value": "GB" }]
}
]
}
}
Cada entrada en response.values representa una dimensión solicitada. Cada objeto en values tiene:
| Campo | Descripción |
|---|---|
| value | El valor bruto de la dimensión. Úsalo al construir consultas filter. |
| displayValue | Una etiqueta legible por humanos para el valor de la dimensión. Solo presente para dimensiones tipo ID, como IDs de productos. Omitido para la mayoría de dimensiones, incluida Country. Puede diferir de value para dimensiones como IDs de productos o nombres de pasos del embudo. |
Los errores usan el mismo envelope done: true y error que el endpoint de métricas. Una dimensión no soportada para la métrica especificada devuelve 400 con código 2001. Ve Errores Comunes.
Consultas Comunes
Los siguientes ejemplos muestran consultas comunes, incluyendo métricas disponibles en las páginas de analíticas del Tablero del Creador.
Ingresos
Consultar ingresos diarios en Robux
Retención D1
Consultar retención D1
Usuarios nuevos vs. usuarios que regresan
Consultar DAU desglosado por nuevos vs. regresados
Agregación semanal
Usa una granularidad más gruesa para una vista de largo alcance con menos puntos de datos. En granularidad OneWeek, cada grupo cuenta usuarios distintos a través del período completo de siete días — no una suma de valores diarios.
Consultar DAU con granularidad semanal
Desglose Top-N
Para clasificar por una métrica y mostrar otra para el mismo conjunto de valores, usa dos solicitudes. Por ejemplo, para ver la conversión de usuarios que pagan para los 5 principales países por DAU:
Paso 1: Descubre los N principales valores de dimensión. Usa granularity: "None" para un solo resultado agregado y limit para limitar el número de series devueltas:
Descubrir los 5 principales países por DAU
Paso 2: Consulta la métrica de visualización, filtrada a los valores devueltos en el paso 1:
Conversión de usuarios que pagan para los 5 principales países
Pasos del embudo
Los embudos muestran cómo los usuarios progresan a través de una secuencia definida de pasos en tu experiencia. Consultar métricas de embudo requiere dos solicitudes, porque los IDs de los pasos son dinámicos.
Paso 1: Descubre los pasos del embudo. Un paso del embudo solo aparece en resultados para días en los que al menos un usuario alcanzó ese paso. Usar un vistazo más largo (90 días es un predeterminado seguro) asegura que los pasos que se alcanzan con poca frecuencia aún aparezcan en la respuesta de descubrimiento. Usa granularity: "None" para obtener un solo resultado agregado por paso:
Descubrir pasos del embudo para el embudo de Niveles
Paso 2: Consulta la métrica del embudo para cada paso, filtrando a los IDs de los pasos devueltos en el paso 1:
Tasa de abandono de usuarios por paso para el embudo de Niveles
Errores Comunes
La mayoría de los errores se devuelven como fallos de operaciones de consulta: el cuerpo de respuesta incluye "done": true y un objeto error con un code numérico y una cadena message. Los errores de autenticación y de recursos (401, 404) son respuestas HTTP simples sin envelope en el cuerpo, por lo que la tabla a continuación muestra — para sus códigos de error.
| Estado | Código | Causa | Resolución |
|---|---|---|---|
| 400 | 2001 | Falta un campo requerido o un valor de campo es inválido (por ejemplo, una metric o granularity no reconocida). | Verifica la tabla Campos del Cuerpo de Solicitud y asegúrate de que todos los valores estén escritos correctamente. |
| 400 | 2001 | La granularidad solicitada no es soportada para la métrica o rango de fechas especificado. | Ve Opciones de Granularidad. Para rangos de fechas superiores a dos años, usa OneWeek, OneMonth, o None. |
| 400 | 2001 | Una dimensión en filter o breakdown no es soportada para la métrica especificada. | Ve Métricas Soportadas. |
| 400 | 2001 | El startTime excede el período de retención de datos para la métrica. | Las métricas estándar retienen datos hasta por cuatro años. Las métricas de rendimiento retienen datos por 28 días. |
| 401 | — | El encabezado x-api-key falta, es inválido, ha sido revocado, o la clave no tiene el permiso de analíticas del universo para este universo. | Verifica el valor de la clave y confirma que la clave de API tiene los permisos correctos en el Tablero del Creador. |
| 404 | — | El ID de operación no existe. | Confirma el ID de operación devuelto en la respuesta inicial, y verifica que el ID de universo sea correcto. |
| 429 | 3000 | La consulta excedió el presupuesto de puntos de datos. | Reduce el rango de fechas, usa una granularidad más gruesa, o reduce el número de series de desglose utilizando limit. |
| 500 | 2000 | Ocurrió un error inesperado del servidor. | Reintenta la solicitud. Si el error persiste, crea una nueva publicación en DevForum. |
| 503 | 2002 | Ocurrió un fallo transitorio. | Reintenta la solicitud después de un breve retraso. |
| 504 | 1000 | La consulta se agotó después del número máximo de reintentos. | Prueba con un rango de fechas más corto, menos desgloses, o una granularidad más gruesa. |