Analytik

Die Analytics Query API ermöglicht es Ihnen, aggregierte Erfahrungsmetriken über einen Datumsbereich abzufragen. Diese API unterstützt:

• Abfragen von täglich aktiven Benutzern (DAU), Einnahmen, Retention und anderen Metriken für Ihre Erfahrung.
• Filtern und Gruppieren von Ergebnissen nach Dimensionen wie Plattform, Land und Altersgruppe.
• Automatisches Handling langsamer Abfragen als langlaufende Vorgänge, für die Sie auf Ergebnisse abfragen können.

Bevor Sie diese API verwenden, müssen Sie einen API-Schlüssel generieren für Ihre Erfahrung. Fügen Sie beim Erstellen des Schlüssels Ihre Erfahrung zu Zugriffsberechtigungen hinzu und gewähren Sie Zugriff auf die universe.analytics:read-Operation innerhalb des universe-analytics-Systems. Fügen Sie den Schlüssel in den x-api-key-Anforderungs-Header bei jeder Anfrage ein.

Alle Endpunkte verwenden Ihre Universum-ID, die Sie im Creator Dashboard finden können, indem Sie Ihre Erfahrung auswählen und die Universum-ID von der Übersichtsseite kopieren.

Metrik abfragen

Um eine Metrik für Ihre Erfahrung abzufragen:

1. Kopieren Sie den API-Schlüssel in den x-api-key-Anforderungs-Header.
2. Ersetzen Sie ${UniverseId} in der URL durch die Universum-ID Ihrer Erfahrung.
3. Setzen Sie metric auf die Metrik, die Sie abfragen möchten, wie z. B. DailyActiveUsers.
4. Setzen Sie granularity auf eine unterstützte Zeitspanne, wie z. B. OneDay. Siehe Granularitätsoptionen.
5. Setzen Sie startTime und endTime auf den gewünschten Datumsbereich unter Verwendung von RFC 3339 UTC-Zeitstempeln.
6. Senden Sie die Anfrage.

Täglich aktive Benutzer abfragen
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"
}'

Die meisten Abfragen werden sofort abgeschlossen und geben 200 OK zurück:

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

Für große Datumsbereiche kann die API 202 Accepted mit "done": false zurückgeben. Siehe Langlaufende Vorgänge.

Felder im Anforderungskörper

Die früheste startTime, die Sie verwenden können, hängt von der Metrikart ab:

• Standardmetriken (Engagement, Monetarisierung, Akquisition, Retention): bis zu 4 Jahre Historie.
• Leistungsmetriken (Absturzrate, Bildfrequenz usw.): bis zu 28 Tage Historie.

Das Abfragen über den Zeitraum hinaus führt zu einem 400-Fehler mit dem Code 2001.

Langlaufende Vorgänge

Die meisten Abfragen werden sofort abgeschlossen und geben 200 OK mit "done": true zurück. Für Abfragen mit großen Datumsbereichen oder vielen Aufgliederungsserien gibt die API 202 Accepted mit "done": false und einem path zum Abfragen zurück.

Ausstehend (202):

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

Wenn done false ist, senden Sie eine GET-Anfrage an https://apis.roblox.com/analytics-query-api/{path}, wobei Sie {path} durch den path-Wert aus der Antwort ersetzen — mit dem gleichen x-api-key-Header. Wiederholen Sie dies, bis done true ist.

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

Ein leeres breakdowns-Array zeigt an, dass keine Aufgliederung angefordert wurde. Wenn eine Aufgliederung verwendet wird, entspricht jedes Element in response.values einem Dimensionwert. Siehe Aufgliederungen verwenden.

Wenn die Operation fehlschlägt, enthält der Körper error anstelle von response:

{
  "path": "path/to/poll",
  "done": true,
  "metadata": {
    "createdTime": "2026-01-15T00:00:00Z"
  },
  "error": {
    "code": 2001,
    "message": "Die angeforderte Granularität wird für diese Metrik nicht unterstützt."
  }
}

Jedes Element in response.values stellt eine Serie dar, eine pro Dimensionwert, wenn eine Aufgliederung verwendet wird, oder einen einzelnen Eintrag mit breakdowns: [], wenn keine Aufgliederung angefordert wurde. Jeder Datenpunkt in dataPoints hat:

Textwertige Metriken

Die meisten Metriken sind numerisch und geben ihr Ergebnis in value zurück. Einige Metriken beschreiben jedoch jeden Datenpunkt mit Text anstelle einer Zahl. Für diese wird der Datenwert in einem stringValues-Array zurückgegeben und value ist nicht aussagekräftig. Das Feld stringValues wird vollständig für numerische Metriken weggelassen.

Zum Beispiel berichtet ThumbnailWinningSegments die gewinnenden Thumbnail-Segmente für jede Zeitspanne als Liste von Strings:

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

Datenpunktstatus

Granularitätsoptionen

Das Feld granularity steuert die Größe jeder Zeitspanne in der Antwort. Die Zeitspannen-Grenzen sind auf UTC ausgerichtet. Zum Beispiel laufen OneDay-Zeitspannen von Mitternacht UTC bis Mitternacht UTC, so dass jede UTC-Verschiebung in startTime oder endTime in UTC normalisiert wird, bevor sie gruppiert wird.

Nicht jede Metrik unterstützt jede Granularität. Siehe Unterstützte Metriken für Details.

Aufgliederungen verwenden

Nicht jede Metrik unterstützt jede Aufgliederung. Siehe Unterstützte Metriken, um zu sehen, welche Aufgliederungen für jede Metrik verfügbar sind.

Aufgliederungen gruppieren die Metrikergebnisse nach einer Dimension und geben eine Serie pro einzigartigem Dimensionwert zurück. Fügen Sie ein breakdown-Array mit einem oder mehreren Dimensionalnamen zu Ihrer Anfrage hinzu.

Einnahmen nach Plattform aufgliedern
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"
}'

Jedes Element in response.values enthält ein breakdowns-Array, das den Dimensionwert für diese Serie identifiziert:

{
  "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 }]
      }
    ]
  }
}

Jedes Objekt in breakdowns hat:

Ergebnisse filtern

Filter schränken die Abfrageergebnisse auf spezifische Dimensionenwerte ein. Fügen Sie Ihrer Anfrage ein filter-Array hinzu, wobei jedes Element eine dimension, die entsprechenden values und die anzuwendende operation spezifiziert.

DAU nur für mobile Geräte abfragen
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"
}'

Filteroperationen

Sie können Filter mit Aufgliederungen in derselben Anfrage kombinieren.

Dimensionenwerte entdecken

Der Endpunkt für Dimensionenwerte listet die verfügbaren Werte für eine oder mehrere Dimensionen einer Metrik über einen Datumsbereich auf, ohne die Metrik selbst zu berechnen. Verwenden Sie ihn, um gültige Werte für filter- und breakdown-Abfragen zu entdecken — beispielsweise Länder, Produkt-IDs oder Trichter-Stufen-IDs.

Um Dimensionenwerte für Ihre Erfahrung abzufragen:

1. Kopieren Sie den API-Schlüssel in den x-api-key-Anforderungs-Header.
2. Ersetzen Sie ${UniverseId} in der URL durch die Universum-ID Ihrer Erfahrung.
3. Setzen Sie metric auf die Metrik, die den Kontext für die Dimensionen liefert.
4. Setzen Sie dimensions auf die Dimensionennamen, für die Sie Werte möchten.
5. Setzen Sie startTime und endTime auf den gewünschten Datumsbereich unter Verwendung von RFC 3339 UTC-Zeitstempeln.
6. Senden Sie die Anfrage.

Länderwerte für DAU entdecken
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"
}'

Felder im Anforderungskörper

Die meisten Abfragen werden sofort abgeschlossen und geben 200 OK mit "done": true zurück. Für Abfragen mit großen Datumsbereichen gibt die API 202 Accepted mit "done": false und einem path zum Abfragen zurück. Siehe Langlaufende Vorgänge für den Abfragefluss. Verwenden Sie beim Abfragen den path-Wert aus der Antwort — er verweist auf v1/universes/{universeId}/operations/dimension-values/{operationId}, der sich vom Metriken-Abfragetyp unterscheidet.

Abgeschlossen (200):

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

Jedes Element in response.values stellt eine angeforderte Dimension dar. Jedes Objekt in values hat:

Fehler verwenden denselben done: true- und error-Envelope wie der Metriken-Endpunkt. Eine nicht unterstützte Dimension für die angegebene Metrik führt zu 400 mit dem Code 2001. Siehe Häufige Fehler.

Häufige Abfragen

Die folgenden Beispiele zeigen häufige Abfragen, darunter Metriken, die auf den Analyse-Seiten des Creator Dashboard verfügbar sind.

Einnahmen

Tägliche Einnahmen in Robux abfragen
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"
}'

D1 Retention

D1 Retention abfragen
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"
}'

Neue Benutzer vs. zurückkehrende Benutzer

DAU nach neuen und zurückkehrenden Benutzern aufgliedern
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"
}'

Wöchentliche Aggregation

Verwenden Sie eine gröbere Granularität für eine längerfristige Ansicht mit weniger Datenpunkten. Bei OneWeek-Granularität zählt jeder Eimer die eindeutigen Benutzer über den gesamten Zeitraum von sieben Tagen — nicht die Summe der täglichen Werte.

DAU bei wöchentlicher Granularität abfragen
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"
}'

Top-N Aufgliederung

Um nach einer Metrik zu rangieren und eine andere für denselben Satz von Werten anzuzeigen, verwenden Sie zwei Anfragen. Um beispielsweise die Konversion von zahlenden Benutzern für die 5 Hauptländer nach DAU zu sehen:

Schritt 1: Entdecken Sie die Top-N Dimensionenwerte. Verwenden Sie granularity: "None" für ein aggregiertes Ergebnis und limit, um die Anzahl der zurückgegebenen Serien zu begrenzen:

Top 5 Länder nach DAU entdecken
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
}'

Schritt 2: Abfragen der Anzeigemetrik, gefiltert nach den in Schritt 1 zurückgegebenen Werten:

Konversion von zahlenden Benutzern für die Top 5 Länder
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"
}'

Trichterstufen

Trichter zeigen, wie Benutzer durch eine definierte Sequenz von Stufen in Ihrer Erfahrung fortschreiten. Das Abfragen von Trichtermetriken erfordert zwei Anfragen, da die Stufen-IDs dynamisch sind.

Schritt 1: Entdecken Sie die Trichterstufen. Eine Trichterstufe erscheint nur in Ergebnissen für Tage, an denen mindestens ein Benutzer diese Stufe erreicht hat. Verwenden Sie einen längeren Rückblick (90 Tage ist ein sicheres Standardmaß), um sicherzustellen, dass auch selten erreichte Stufen in der Entdeckungsantwort erscheinen. Verwenden Sie granularity: "None", um ein aggregiertes Ergebnis pro Schritt zu erhalten:

Trichterstufen für den Levels-Trichter entdecken
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"
}'

Schritt 2: Abfragen der Trichtermetrik für jede Stufe, gefiltert nach den in Schritt 1 zurückgegebenen Stufen-IDs:

Benutzerabsprungrate pro Schritt für den Levels-Trichter
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"
}'

Häufige Fehler

Die meisten Fehler werden als Abfragevorgangsfehler zurückgegeben: Der Antwortkörper enthält "done": true und ein error-Objekt mit einem numerischen code und einer message-Zeichenfolge. Authentifizierungs- und Ressourcenfehler (401, 404) sind einfache HTTP-Antworten ohne Body-Envelope, weshalb die Tabelle unten — für ihre Fehlercodes zeigt.