Analisi

L'API di Query delle Analisi ti consente di interrogare metriche aggregate sull'esperienza su un intervallo di date. Questa API supporta:

• L'interrogazione degli utenti attivi giornalieri (DAU), delle entrate, della retention e di altre metriche per la tua esperienza.
• Il filtraggio e il raggruppamento dei risultati per dimensioni come piattaforma, paese e fasce d'età.
• La gestione automatica delle query lente come operazioni di lunga durata per cui puoi interrogare i risultati.

Prima di utilizzare questa API, devi generare una chiave API per la tua esperienza. Quando crei la chiave, aggiungi la tua esperienza a Access Permissions e concedi accesso all'operazione universe.analytics:read all'interno del sistema universe-analytics. Includi la chiave nell'intestazione della richiesta x-api-key in ogni richiesta.

Tutti gli endpoint utilizzano il tuo ID universo, che puoi trovare nel Creator Dashboard selezionando la tua esperienza e copiando l'ID Universo dalla pagina di panoramica.

Interrogare una metrica

Per interrogare una metrica per la tua esperienza:

1. Copia la chiave API nell'intestazione della richiesta x-api-key.
2. Sostituisci ${UniverseId} nell'URL con l'ID universo della tua esperienza.
3. Imposta metric sulla metrica che desideri interrogare, come DailyActiveUsers.
4. Imposta granularity su una dimensione del bucket temporale supportata, come OneDay. Vedi Opzioni di granularità.
5. Imposta startTime e endTime sull'intervallo di date desiderato, utilizzando i timestamp UTC RFC 3339.
6. Invia la richiesta.

Interroga utenti attivi giornalieri
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"
}'

La maggior parte delle interrogazioni viene completata immediatamente e restituisce 200 OK:

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

Per intervalli di date ampi, l'API potrebbe restituire 202 Accepted con "done": false. Vedi Operazioni di lunga durata.

Campi del corpo della richiesta

Il più precoce startTime che puoi utilizzare dipende dal tipo di metrica:

• Metriche standard (coinvolgimento, monetizzazione, acquisizione, retention): fino a 4 anni di storia.
• Metriche di performance (tasso di crash, frame rate, ecc.): fino a 28 giorni di storia.

Interrogare oltre il periodo di retention restituisce un errore 400 con codice 2001.

Operazioni di lunga durata

La maggior parte delle interrogazioni viene completata immediatamente e restituisce 200 OK con "done": true. Per interrogazioni con ampi intervalli di date o molte serie di raggruppamento, l'API restituisce 202 Accepted con "done": false e un path da interrogare.

In sospeso (202):

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

Quando done è false, invia una richiesta GET a https://apis.roblox.com/analytics-query-api/{path} — sostituendo {path} con il valore path dalla risposta — utilizzando la stessa intestazione x-api-key. Ripeti fino a quando done è true.

Completato (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 vuoto indica che non è stato richiesto alcun raggruppamento. Quando viene utilizzato un raggruppamento, ogni voce in response.values corrisponde a un valore di dimensione. Vedi Usa i raggruppamenti.

Quando l'operazione fallisce, il corpo contiene error invece di response:

{
  "path": "path/to/poll",
  "done": true,
  "metadata": {
    "createdTime": "2026-01-15T00:00:00Z"
  },
  "error": {
    "code": 2001,
    "message": "La granularità richiesta non è supportata per questa metrica."
  }
}

Ogni voce in response.values rappresenta una serie, una per valore di dimensione quando viene utilizzato un raggruppamento, o una singola voce con breakdowns: [] quando non è stato richiesto alcun raggruppamento. Ogni punto dati in dataPoints ha:

Metriche a valore testuale

La maggior parte delle metriche è numerica e riporta il risultato in value. Alcune metriche descrivono invece ciascun punto dati con testo piuttosto che con un numero. Per queste, i dati vengono restituiti in un array stringValues e value non ha significato. Il campo stringValues è completamente omesso per le metriche numeriche.

Ad esempio, ThumbnailWinningSegments riporta i segmenti di miniatura vincenti per ogni bucket temporale come un elenco di stringhe:

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

Stato del punto dati

Opzioni di granularità

Il campo granularity controlla la dimensione di ciascun bucket temporale nella risposta. I confini dei bucket sono allineati all'UTC. Ad esempio, i bucket OneDay vanno dalla mezzanotte UTC alla mezzanotte UTC, quindi eventuali offset UTC in startTime o endTime vengono normalizzati all'UTC prima del raggruppamento.

Non tutti i metriche supportano tutte le granularità. Vedi Metriche supportate per i dettagli.

Usa i raggruppamenti

Non tutte le metriche supportano tutti i raggruppamenti. Vedi Metriche supportate per quali raggruppamenti sono disponibili per ciascuna metrica.

I raggruppamenti raggruppano i risultati della metrica per una dimensione, restituendo una serie per ogni valore di dimensione unico. Aggiungi un array breakdown con uno o più nomi di dimensione alla tua richiesta.

Interroga le entrate suddivise per piattaforma
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"
}'

Ogni voce in response.values include un array breakdowns che identifica il valore della dimensione per quella 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 }]
      }
    ]
  }
}

Ogni oggetto in breakdowns ha:

Filtra i risultati

I filtri restringono i risultati della query a valori di dimensione specifici. Aggiungi un array filter alla tua richiesta, dove ogni voce specifica una dimension, i values da abbinare e l'operation da applicare.

Interroga DAU solo per dispositivi mobili
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"
}'

Operazioni di filtro

Puoi combinare filtri con raggruppamenti nella stessa richiesta.

Scopri i valori di dimensione

L'endpoint dei valori di dimensione elenca i valori disponibili per una o più dimensioni di una metrica su un intervallo di date, senza calcolare la metrica stessa. Usalo per scoprire valori validi per le query filter e breakdown — ad esempio, paesi, ID prodotto o ID di passi del funnel.

Per interrogare i valori di dimensione della tua esperienza:

1. Copia la chiave API nell'intestazione della richiesta x-api-key.
2. Sostituisci ${UniverseId} nell'URL con l'ID universo della tua esperienza.
3. Imposta metric sulla metrica che fornisce il contesto per le dimensioni.
4. Imposta dimensions sui nomi delle dimensioni per cui desideri valori.
5. Imposta startTime e endTime sull'intervallo di date desiderato, utilizzando i timestamp UTC RFC 3339.
6. Invia la richiesta.

Scopri i valori dei paesi per 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"
}'

Campi del corpo della richiesta

La maggior parte delle interrogazioni sono completate immediatamente e restituiscono 200 OK con "done": true. Per interrogazioni con ampi intervalli di date, l'API restituisce 202 Accepted con "done": false e un path da interrogare. Vedi Operazioni di lunga durata per il flusso di polling. Durante il polling, utilizza il valore path dalla risposta — indica a v1/universes/{universeId}/operations/dimension-values/{operationId}, distinto dal percorso di polling delle metriche.

Completato (200):

{
  "path": "path/to/poll",
  "done": true,
  "metadata": {
    "createdTime": "2026-01-15T00:00:00Z"
  },
  "response": {
    "values": [
      {
        "dimension": "Country",
        "values": [{ "value": "US" }, { "value": "GB" }]
      }
    ]
  }
}

Ogni voce in response.values rappresenta una dimensione richiesta. Ogni oggetto in values ha:

Gli errori utilizzano lo stesso involucro done: true e error come l'endpoint delle metriche. Una dimensione non supportata per la metrica specificata restituisce 400 con codice 2001. Vedi Errori comuni.

Query comuni

I seguenti esempi mostrano query comuni, comprese metriche disponibili nelle pagine di analisi del Creator Dashboard.

Entrate

Interroga entrate giornaliere in 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"
}'

Retention D1

Interroga retention 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"
}'

Nuovi utenti vs. utenti di ritorno

Interroga DAU suddivisi per nuovi vs. ritorno
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"
}'

Aggregazione settimanale

Utilizza una granularità più grossolana per una vista a lungo raggio con meno punti dati. Con una granularità di OneWeek, ogni bucket conta utenti distinti durante il periodo di sette giorni — non una somma dei valori giornalieri.

Interroga DAU con granularità settimanale
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"
}'

Suddivisione Top-N

Per classificare per una metrica e visualizzarne un'altra per lo stesso insieme di valori, usa due richieste. Ad esempio, per vedere il tasso di conversione degli utenti paganti per i primi 5 paesi per DAU:

Passo 1: Scopri i valori di dimensione Top N. Usa granularity: "None" per un singolo risultato aggregato e limit per limitare il numero di serie restituite:

Scopri i primi 5 paesi per 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: Interroga la metrica di visualizzazione, filtrata ai valori restituiti nel passaggio 1:

Conversione degli utenti paganti per i primi 5 paesi
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"
}'

Passaggi del funnel

I funnel mostrano come gli utenti progrediscono attraverso una sequenza definita di passaggi nella tua esperienza. Interrogare le metriche del funnel richiede due richieste, perché gli ID dei passaggi sono dinamici.

Passo 1: Scopri i passaggi del funnel. Un passaggio del funnel appare solo nei risultati per i giorni in cui almeno un utente ha raggiunto quel passaggio. Utilizzare un intervallo di tempo più lungo (90 giorni è un default sicuro) assicura che i passaggi raramente raggiunti appaiano ancora nella risposta di scoperta. Usa granularity: "None" per ottenere un singolo risultato aggregato per passaggio:

Scopri i passaggi del funnel per il funnel di Livelli
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: Interroga la metrica del funnel per ciascun passaggio, filtrando sugli ID dei passaggi restituiti nel passaggio 1:

Tasso di abbandono degli utenti per passo per il funnel di Livelli
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"
}'

Errori comuni

La maggior parte degli errori viene restituita come errori di fallimento delle query: il corpo della risposta include "done": true e un oggetto error con un code numerico e una stringa message. Gli errori di autenticazione e risorse (401, 404) sono risposte HTTP semplici senza involucro del corpo, motivo per cui la tabella qui sotto mostra — per i loro codici di errore.