Analyse

L'API d'Interrogation d'Analyse vous permet d'interroger des métriques d'expérience agrégées sur une plage de dates. Cette API prend en charge :

• L'interrogation des utilisateurs actifs quotidiens (DAU), du revenu, de la rétention et d'autres métriques pour votre expérience.
• Le filtrage et le regroupement des résultats par dimensions telles que la plateforme, le pays et le groupe d'âge.
• La gestion automatique des requêtes lentes en tant qu'opérations de longue durée dont vous pouvez interroger les résultats.

Avant d'utiliser cette API, vous devez générer une clé API pour votre expérience. Lors de la création de la clé, ajoutez votre expérience aux Permissions d'accès et accordez-lui l'accès à l'opération universe.analytics:read au sein du système universe-analytics. Incluez la clé dans l'en-tête de requête x-api-key à chaque requête.

Tous les points de terminaison utilisent votre ID d'univers, que vous pouvez trouver sur le Tableau de bord Créateur en sélectionnant votre expérience et en copiant l'ID d'univers depuis la page d'aperçu.

Interroger une métrique

Pour interroger une métrique pour votre expérience :

1. Copiez la clé API dans l'en-tête de requête x-api-key.
2. Remplacez ${UniverseId} dans l'URL par l'ID d'univers de votre expérience.
3. Définissez metric sur la métrique que vous souhaitez interroger, comme DailyActiveUsers.
4. Définissez granularity sur une taille de bucket temporel prise en charge, comme OneDay. Voir Options de granularité.
5. Définissez startTime et endTime sur la plage de dates que vous souhaitez, en utilisant des horodatages UTC RFC 3339.
6. Envoyez la requête.

Interroger les utilisateurs actifs quotidiens
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 plupart des requêtes se terminent immédiatement et renvoient 200 OK :

Réponse (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 }
        ]
      }
    ]
  }
}

Pour de grandes plages de dates, l'API peut renvoyer 202 Accepted avec "done": false. Voir Opérations de longue durée.

Champs du corps de la requête

Le startTime le plus précoce que vous pouvez utiliser dépend du type de métrique :

• Métriques standard (engagement, monétisation, acquisition, rétention) : jusqu'à 4 ans d'historique.
• Métriques de performance (taux de crash, taux de fréquence, etc.) : jusqu'à 28 jours d'historique.

Interroger au-delà de la période de rétention renvoie une erreur 400 avec le code 2001.

Opérations de longue durée

La plupart des requêtes se terminent immédiatement et renvoient 200 OK avec "done": true. Pour les requêtes avec de grandes plages de dates ou de nombreuses séries de répartition, l'API renvoie 202 Accepted avec "done": false et un path à interroger.

En attente (202) :

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

Lorsque done est false, envoyez une requête GET à https://apis.roblox.com/analytics-query-api/{path} — en remplaçant {path} par la valeur path de la réponse — en utilisant le même en-tête x-api-key. Répétez jusqu'à ce que done soit true.

Terminé (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 tableau breakdowns vide indique aucune répartition demandée. Lorsqu'une répartition est utilisée, chaque entrée dans response.values correspond à une valeur de dimension. Voir Utiliser des répartitions.

Lorsque l'opération échoue, le corps contient error au lieu de response :

{
  "path": "path/to/poll",
  "done": true,
  "metadata": {
    "createdTime": "2026-01-15T00:00:00Z"
  },
  "error": {
    "code": 2001,
    "message": "La granularité demandée n'est pas prise en charge pour cette métrique."
  }
}

Chaque entrée dans response.values représente une série, une par valeur de dimension lorsqu'une répartition est utilisée, ou une seule entrée avec breakdowns: [] lorsque aucune répartition n'est demandée. Chaque point de données dans dataPoints a :

Métriques à valeur textuelle

La plupart des métriques sont numériques et rapportent leur résultat dans value. Quelques métriques décrivent plutôt chaque point de données par du texte plutôt que par un nombre. Pour celles-ci, les données sont renvoyées dans un tableau stringValues et value n'est pas significatif. Le champ stringValues est omis entièrement pour les métriques numériques.

Par exemple, ThumbnailWinningSegments rapporte les segments de vignette gagnants pour chaque bucket temporel sous forme de liste de chaînes :

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

État du point de données

Options de granularité

Le champ granularity contrôle la taille de chaque bucket temporel dans la réponse. Les frontières des buckets sont alignées sur l'UTC. Par exemple, les buckets OneDay s'étendent de minuit UTC à minuit UTC, donc tout décalage UTC dans startTime ou endTime est normalisé à l'UTC avant le regroupement.

Toutes les métriques ne prennent pas en charge chaque granularité. Voir Métriques prises en charge pour plus de détails.

Utiliser des répartitions

Toutes les métriques ne prennent pas en charge toutes les répartitions. Voir Métriques prises en charge pour savoir quelles répartitions sont disponibles pour chaque métrique.

Les répartitions regroupent les résultats des métriques par une dimension, renvoyant une série pour chaque valeur unique de dimension. Ajoutez un tableau breakdown avec un ou plusieurs noms de dimension à votre requête.

Interroger les revenus ventilés par plateforme
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"
}'

Chaque entrée dans response.values inclut un tableau breakdowns identifiant la valeur de dimension pour cette 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 }]
      }
    ]
  }
}

Chaque objet dans breakdowns contient :

Filtrer les résultats

Les filtres restreignent les résultats de la requête à des valeurs de dimensions spécifiques. Ajoutez un tableau filter à votre requête, où chaque entrée précise une dimension, les values à correspondre, et l'operation à appliquer.

Interroger les DAU uniquement pour les appareils mobiles
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"
}'

Opérations de filtrage

Vous pouvez combiner des filtres avec des répartitions dans la même requête.

Découvrir les valeurs des dimensions

Le point de terminaison des valeurs de dimensions énumère les valeurs disponibles pour une ou plusieurs dimensions d'une métrique sur une plage de dates, sans calculer la métrique elle-même. Utilisez-le pour découvrir des valeurs valides pour les requêtes filter et breakdown — par exemple, des pays, des ID de produit ou des ID d'étapes de funnel.

Pour interroger les valeurs de dimension pour votre expérience :

1. Copiez la clé API dans l'en-tête de requête x-api-key.
2. Remplacez ${UniverseId} dans l'URL par l'ID d'univers de votre expérience.
3. Définissez metric sur la métrique qui fournit le contexte pour les dimensions.
4. Définissez dimensions sur les noms de dimension pour lesquels vous souhaitez obtenir des valeurs.
5. Définissez startTime et endTime sur la plage de dates que vous souhaitez, en utilisant des horodatages UTC RFC 3339.
6. Envoyez la requête.

Découvrir les valeurs des pays pour 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"
}'

Champs du corps de la requête

La plupart des requêtes se terminent immédiatement et renvoient 200 OK avec "done": true. Pour les requêtes avec de grandes plages de dates, l'API renvoie 202 Accepted avec "done": false et un path à interroger. Voir Opérations de longue durée pour le flux d'interrogation. Lors de l'interrogation, utilisez la valeur path de la réponse — elle pointe vers v1/universes/{universeId}/operations/dimension-values/{operationId}, distincte du chemin d'interrogation des métriques.

Terminé (200) :

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

Chaque entrée dans response.values représente une dimension demandée. Chaque objet dans values a :

Les erreurs utilisent le même done: true et l'enveloppe error que l'endpoint des métriques. Une dimension non prise en charge pour la métrique spécifiée renvoie 400 avec le code 2001. Voir Erreurs courantes.

Requêtes courantes

Les exemples suivants montrent des requêtes courantes, y compris des métriques disponibles sur les pages d'analyse du Tableau de bord Créateur.

Revenu

Interroger le revenu quotidien en 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"
}'

Rétention D1

Interroger la rétention 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"
}'

Nouveaux utilisateurs vs. utilisateurs de retour

Interroger les DAU ventilés par nouveaux utilisateurs vs utilisateurs de retour
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"
}'

Agrégation hebdomadaire

Utilisez une granularité plus grossière pour une vue de plus longue durée avec moins de points de données. À la granularité OneWeek, chaque bucket compte les utilisateurs distincts sur la période entière de sept jours — pas une somme des valeurs quotidiennes.

Interroger les DAU à une granularité hebdomadaire
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"
}'

Ventilation Top-N

Pour classer par une métrique et afficher une autre pour le même ensemble de valeurs, utilisez deux requêtes. Par exemple, pour voir la conversion d'utilisateurs payants pour les 5 principaux pays par DAU :

Étape 1 : Découvrir les valeurs des dimensions top N. Utilisez granularity: "None" pour un seul résultat agrégé et limit pour limiter le nombre de séries renvoyées :

Découvrir les 5 principaux pays par 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
}'

Étape 2 : Interroger la métrique d'affichage, filtrée aux valeurs renvoyées à l'étape 1 :

Conversion d'utilisateurs payants pour les 5 principaux pays
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"
}'

Étapes de funnel

Les funnels montrent comment les utilisateurs progressent à travers une séquence définie d'étapes dans votre expérience. Interroger des métriques de funnel nécessite deux requêtes, car les ID des étapes sont dynamiques.

Étape 1 : Découvrir les étapes du funnel. Une étape de funnel n'apparaît dans les résultats que pour les jours où au moins un utilisateur a atteint cette étape. Utiliser un retour en arrière plus long (90 jours est un bon défaut) garantit que les étapes rarement atteintes apparaissent toujours dans la réponse de découverte. Utilisez granularity: "None" pour obtenir un seul résultat agrégé par étape :

Découvrir les étapes du funnel pour le funnel Niveaux
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"
}'

Étape 2 : Interroger la métrique du funnel pour chaque étape, filtrée aux ID des étapes renvoyées à l'étape 1 :

Taux d'attrition des utilisateurs par étape pour le funnel Niveaux
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"
}'

Erreurs courantes

La plupart des erreurs sont renvoyées comme des échecs d'opération de requête : le corps de la réponse inclut "done": true et un objet error avec un code numérique et une chaîne message. Les erreurs d'authentification et de ressource (401, 404) sont des réponses HTTP simples sans enveloppe de corps, c'est pourquoi le tableau ci-dessous montre — pour leurs codes d'erreur.