Análise

A API de Consulta de Análise permite que você consulte métricas agregadas de experiência em um intervalo de datas. Esta API suporta:

• Consultar usuários ativos diários (DAU), receita, retenção e outras métricas para sua experiência.
• Filtrar e agrupar resultados por dimensões como plataforma, país e faixa etária.
• Lidar automaticamente com consultas lentas como operações de longa duração que você pode consultar para resultados.

Antes de usar esta API, você deve gerar uma chave de API para sua experiência. Ao criar a chave, adicione sua experiência a Permissões de Acesso e conceda acesso à operação universe.analytics:read dentro do sistema universe-analytics. Inclua a chave no cabeçalho de requisição x-api-key em cada requisição.

Todos os pontos finais usam seu ID do universo, que você pode encontrar no Painel do Criador selecionando sua experiência e copiando o ID do Universo da página de visão geral.

Consultar uma métrica

Para consultar uma métrica para sua experiência:

1. Copie a chave da API para o cabeçalho de requisição x-api-key.
2. Substitua ${UniverseId} na URL pelo ID do universo de sua experiência.
3. Defina metric para a métrica que você deseja consultar, como DailyActiveUsers.
4. Defina granularity para um tamanho de intervalo de tempo suportado, como OneDay. Veja Opções de Granularidade.
5. Defina startTime e endTime para o intervalo de datas desejado, usando timestamps UTC RFC 3339.
6. Envie a requisição.

Consultar usuários ativos diários
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"
}'

A maioria das consultas é completada imediatamente e retorna 200 OK:

Resposta (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 intervalos de datas grandes, a API pode retornar 202 Accepted com "done": false. Veja Operações de longa duração.

Campos do corpo da requisição

O mais cedo startTime que você pode usar depende do tipo de métrica:

• Métricas padrão (engajamento, monetização, aquisição, retenção): até 4 anos de histórico.
• Métricas de performance (taxa de falhas, taxa de quadros, etc.): até 28 dias de histórico.

Consultar além do período de retenção retorna um erro 400 com código 2001.

Operações de longa duração

A maioria das consultas é completada imediatamente e retorna 200 OK com "done": true. Para consultas com grandes intervalos de datas ou muitas séries de agrupamento, a API retorna 202 Accepted com "done": false e um path para consultar.

Pendente (202):

{
  "path": "path/to/poll",
  "done": false,
  "metadata": {
    "createdTime": "2026-01-15T00:00:00Z"
  }
}

Quando done é false, envie uma requisição GET para https://apis.roblox.com/analytics-query-api/{path} — substituindo {path} pelo valor path da resposta — usando o mesmo cabeçalho x-api-key. Repita até que done seja true.

Completo (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
          }
        ]
      }
    ]
  }
}

Um array breakdowns vazio indica que nenhum agrupamento foi solicitado. Quando um agrupamento é utilizado, cada entrada em response.values corresponde a um valor de dimensão. Veja Usar agrupamentos.

Quando a operação falha, o corpo contém error em vez de response:

{
  "path": "path/to/poll",
  "done": true,
  "metadata": {
    "createdTime": "2026-01-15T00:00:00Z"
  },
  "error": {
    "code": 2001,
    "message": "A granularidade solicitada não é suportada para esta métrica."
  }
}

Cada entrada em response.values representa uma série, uma por valor de dimensão quando um agrupamento é usado, ou uma única entrada com breakdowns: [] quando nenhum agrupamento é solicitado. Cada ponto de dados em dataPoints possui:

Métricas com valores de texto

A maioria das métricas são numéricas e relatam seu resultado em value. Algumas métricas, em vez disso, descrevem cada ponto de dados com texto ao invés de um número. Para essas, os dados são retornados em um array stringValues e value não é significativo. O campo stringValues é completamente omitido para métricas numéricas.

Por exemplo, ThumbnailWinningSegments relata os segmentos de miniatura vencedores para cada intervalo de tempo como uma lista de strings:

{
  "time": "2026-01-01T00:00:00Z",
  "value": 0,
  "stringValues": ["TopEngagement", "HighCTR"]
}

Status do ponto de dados

Opções de Granularidade

O campo granularity controla o tamanho de cada intervalo de tempo na resposta. Os limites dos intervalos estão alinhados com o UTC. Por exemplo, os intervalos OneDay vão da meia-noite UTC à meia-noite UTC, de modo que qualquer deslocamento UTC em startTime ou endTime é normalizado para UTC antes do agrupamento.

Nem toda métrica suporta toda granularidade. Veja Métricas suportadas para detalhes.

Usar agrupamentos

Nem toda métrica suporta todo agrupamento. Veja Métricas suportadas para quais agrupamentos estão disponíveis para cada métrica.

Agrupamentos agrupam resultados de métricas por uma dimensão, retornando uma série por valor de dimensão único. Adicione um array breakdown com um ou mais nomes de dimensão à sua requisição.

Consultar receita agrupada por plataforma
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"
}'

Cada entrada em response.values inclui um array breakdowns identificando o valor de dimensão para essa série:

{
  "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 em breakdowns tem:

Filtrar resultados

Filtros restringem resultados da consulta a valores específicos de dimensões. Adicione um array filter à sua requisição, onde cada entrada especifica uma dimension, os values a serem correspondidos e a operation a ser aplicada.

Consultar DAU apenas para dispositivos móveis
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"
}'

Operações de filtro

Você pode combinar filtros com agrupamentos na mesma requisição.

Descobrir valores de dimensão

O ponto final de valores de dimensão lista os valores disponíveis para uma ou mais dimensões de uma métrica em um intervalo de datas, sem calcular a métrica em si. Use-o para descobrir valores válidos para consultas de filter e breakdown — por exemplo, países, IDs de produtos ou IDs de etapas de funil.

Para consultar valores de dimensão para sua experiência:

1. Copie a chave da API para o cabeçalho de requisição x-api-key.
2. Substitua ${UniverseId} na URL pelo ID do universo de sua experiência.
3. Defina metric para a métrica que fornece contexto para as dimensões.
4. Defina dimensions para os nomes das dimensões para as quais você deseja valores.
5. Defina startTime e endTime para o intervalo de datas desejado, usando timestamps UTC RFC 3339.
6. Envie a requisição.

Descobrir valores de país para 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"
}'

Campos do corpo da requisição

A maioria das consultas é completada imediatamente e retorna 200 OK com "done": true. Para consultas com grandes intervalos de datas, a API retorna 202 Accepted com "done": false e um path para consultar. Veja Operações de longa duração para o fluxo de consulta. Ao consultar, use o valor path da resposta — ele aponta para v1/universes/{universeId}/operations/dimension-values/{operationId}, distinto do caminho de consulta de métricas.

Completo (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 em response.values representa uma dimensão solicitada. Cada objeto em values tem:

Os erros usam o mesmo envelope done: true e error que o ponto final de métricas. Uma dimensão não suportada para a métrica especificada retorna 400 com código 2001. Veja Erros comuns.

Consultas comuns

Os seguintes exemplos mostram consultas comuns, incluindo métricas disponíveis nas páginas de análises do Painel do Criador.

Receita

Consultar receita diária em 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"
}'

Retenção D1

Consultar retenção 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"
}'

Novos usuários vs. usuários retornando

Consultar DAU agrupado por novos vs. retornando
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"
}'

Agregação semanal

Use uma granularidade mais grossa para uma visão de longo prazo com menos pontos de dados. Na granularidade OneWeek, cada intervalo conta usuários distintos ao longo do período de sete dias — não uma soma de valores diários.

Consultar DAU com granularidade semanal
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"
}'

Quebra Top-N

Para classificar por uma métrica e exibir outra para o mesmo conjunto de valores, use duas requisições. Por exemplo, para ver a conversão de usuários pagantes para os 5 principais países por DAU:

Passo 1: Descubra os N principais valores de dimensão. Use granularity: "None" para um único resultado agregado e limit para limitar o número de séries retornadas:

Descobrir os 5 principais países por 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
}'

Passo 2: Consulte a métrica de exibição, filtrando os valores retornados na etapa 1:

Conversão de usuários pagantes para os 5 principais países
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"
}'

Etapas do funil

Os funis mostram como os usuários progridem através de uma sequência definida de etapas em sua experiência. Consultar métricas de funil requer duas requisições, porque os IDs das etapas são dinâmicos.

Passo 1: Descubra as etapas do funil. Uma etapa do funil só aparece nos resultados em dias em que pelo menos um usuário alcançou essa etapa. Usar um olhar retrospectivo mais longo (90 dias é um padrão seguro) garante que etapas raramente alcançadas ainda apareçam na resposta de descoberta. Use granularity: "None" para obter um único resultado agregado por etapa:

Descobrir etapas do funil para o funil de Níveis
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"
}'

Passo 2: Consulte a métrica do funil para cada etapa, filtrando para os IDs das etapas retornadas na etapa 1:

Taxa de churn dos usuários por etapa para o funil de Níveis
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"
}'

Erros comuns

A maioria dos erros são retornados como falhas de operação de consulta: o corpo da resposta inclui "done": true e um objeto error com um código numérico code e uma string message. Erros de autenticação e de recurso (401, 404) são respostas HTTP simples sem envelope de corpo, razão pela qual a tabela abaixo mostra — para seus códigos de erro.