Analitik

API Query Analitik memungkinkan Anda untuk menanyakan metrik pengalaman yang teragregasi selama rentang tanggal tertentu. API ini mendukung:

• Menanyakan pengguna aktif harian (DAU), pendapatan, retensi, dan metrik lainnya untuk pengalaman Anda.
• Memfilter dan mengelompokkan hasil berdasarkan dimensi seperti platform, negara, dan kelompok usia.
• Menangani secara otomatis kueri yang lambat sebagai operasi jangka panjang yang dapat Anda polling untuk hasilnya.

Sebelum menggunakan API ini, Anda harus menghasilkan kunci API untuk pengalaman Anda. Saat membuat kunci, tambahkan pengalaman Anda ke Izin Akses dan berikan akses ke operasi universe.analytics:read dalam sistem universe-analytics. Sertakan kunci dalam header permintaan x-api-key di setiap permintaan.

Semua titik akhir menggunakan ID alam semesta Anda, yang dapat Anda temukan di Dasbor Pembuat dengan memilih pengalaman Anda dan menyalin ID Alam Semesta dari halaman ringkasan.

Menanyakan metrik

Untuk menanyakan metrik untuk pengalaman Anda:

1. Salin kunci API ke header permintaan x-api-key.
2. Ganti ${UniverseId} dalam URL dengan ID alam semesta pengalaman Anda.
3. Atur metric ke metrik yang ingin Anda kueri, seperti DailyActiveUsers.
4. Atur granularity ke ukuran bucket waktu yang didukung, seperti OneDay. Lihat Opsi Granularitas.
5. Atur startTime dan endTime ke rentang tanggal yang Anda inginkan, menggunakan timestamp UTC RFC 3339.
6. Kirim permintaan.

Kueri pengguna aktif harian
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"
}'

Sebagian besar kueri selesai segera dan mengembalikan 200 OK:

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

Untuk rentang tanggal yang besar, API dapat mengembalikan 202 Accepted dengan "done": false. Lihat Operasi Jangka Panjang.

Bidang tubuh permintaan

startTime yang paling awal yang dapat Anda gunakan bergantung pada jenis metrik:

• Metrik standar (keterlibatan, monetisasi, akuisisi, retensi): hingga 4 tahun histori.
• Metrik kinerja (rasio kerusakan, rasio bingkai, dll.): hingga 28 hari histori.

Menanyakan di luar periode retensi mengembalikan kesalahan 400 dengan kode 2001.

Operasi Jangka Panjang

Sebagian besar kueri selesai segera dan mengembalikan 200 OK dengan "done": true. Untuk kueri dengan rentang tanggal yang besar atau banyak seri pemecahan, API mengembalikan 202 Accepted dengan "done": false dan path untuk polling.

Tertunda (202):

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

Ketika done adalah false, kirim permintaan GET ke https://apis.roblox.com/analytics-query-api/{path} — ganti {path} dengan nilai path dari respons — menggunakan header x-api-key yang sama. Ulangi hingga done adalah true.

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

Array breakdowns yang kosong menunjukkan tidak ada pemecahan yang diminta. Ketika pemecahan digunakan, setiap entri dalam response.values sesuai dengan satu nilai dimensi. Lihat Gunakan pemecahan.

Ketika operasi gagal, tubuh berisi error sebagai pengganti response:

{
  "path": "path/to/poll",
  "done": true,
  "metadata": {
    "createdTime": "2026-01-15T00:00:00Z"
  },
  "error": {
    "code": 2001,
    "message": "Granularitas yang diminta tidak didukung untuk metrik ini."
  }
}

Setiap entri dalam response.values mewakili satu seri, satu per nilai dimensi ketika pemecahan digunakan, atau satu entri dengan breakdowns: [] ketika tidak ada pemecahan yang diminta. Setiap titik data dalam dataPoints memiliki:

Metrik bernilai teks

Sebagian besar metrik bersifat numerik dan melaporkan hasilnya dalam value. Beberapa metrik justru mendeskripsikan setiap titik data dengan teks alih-alih angka. Untuk metrik ini, data dikembalikan dalam array stringValues dan value tidak berarti. Bidang stringValues sepenuhnya dihilangkan untuk metrik numerik.

Sebagai contoh, ThumbnailWinningSegments melaporkan segmen thumbnail yang menang untuk setiap bucket waktu sebagai daftar string:

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

Status titik data

Opsi Granularitas

Bidang granularity mengontrol ukuran setiap bucket waktu dalam respons. Batas bucket diselaraskan ke UTC. Sebagai contoh, bucket OneDay berjalan dari tengah malam UTC hingga tengah malam UTC, sehingga setiap offset UTC dalam startTime atau endTime dinormalisasi ke UTC sebelum pengelompokan.

Tidak setiap metrik mendukung setiap granularitas. Lihat Metrik yang Didukung untuk detailnya.

Gunakan pemecahan

Tidak setiap metrik mendukung setiap pemecahan. Lihat Metrik yang Didukung untuk metrik mana yang tersedia untuk setiap pemecahan.

Pemecahan mengelompokkan hasil metrik berdasarkan dimensi, mengembalikan satu seri per nilai dimensi unik. Tambahkan array breakdown dengan satu atau lebih nama dimensi ke permintaan Anda.

Kueri pendapatan yang dipecah berdasarkan platform
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"
}'

Setiap entri dalam response.values menyertakan array breakdowns yang mengidentifikasi nilai dimensi untuk seri tersebut:

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

Setiap objek dalam breakdowns memiliki:

Filter hasil

Filter mempersempit hasil kueri ke nilai dimensi tertentu. Tambahkan array filter ke permintaan Anda, di mana setiap entri menentukan dimension, values yang cocok, dan operation yang diterapkan.

Kueri DAU untuk perangkat mobile saja
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"
}'

Operasi filter

Anda dapat menggabungkan filter dengan pemecahan dalam permintaan yang sama.

Menemukan nilai dimensi

Titik akhir nilai dimensi mencantumkan nilai yang tersedia untuk satu atau lebih dimensi metrik selama rentang tanggal tertentu, tanpa menghitung metrik itu sendiri. Gunakan untuk menemukan nilai yang valid untuk kueri filter dan breakdown — misalnya, negara, ID produk, atau ID langkah corong.

Untuk menanyakan nilai dimensi untuk pengalaman Anda:

1. Salin kunci API ke header permintaan x-api-key.
2. Ganti ${UniverseId} dalam URL dengan ID alam semesta pengalaman Anda.
3. Atur metric ke metrik yang memberikan konteks untuk dimensi.
4. Atur dimensions ke nama dimensi yang ingin Anda ambil nilainya.
5. Atur startTime dan endTime ke rentang tanggal yang Anda inginkan, menggunakan timestamp UTC RFC 3339.
6. Kirim permintaan.

Temukan nilai negara untuk 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"
}'

Bidang tubuh permintaan

Sebagian besar kueri selesai segera dan mengembalikan 200 OK dengan "done": true. Untuk kueri dengan rentang tanggal yang besar, API mengembalikan 202 Accepted dengan "done": false dan path untuk polling. Lihat Operasi Jangka Panjang untuk alur polling. Saat polling, gunakan nilai path dari respons — itu menunjuk ke v1/universes/{universeId}/operations/dimension-values/{operationId}, terpisah dari jalur polling metrik.

Selesai (200):

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

Setiap entri dalam response.values mewakili satu dimensi yang diminta. Setiap objek dalam values memiliki:

Kesalahan menggunakan envelope done: true dan error yang sama seperti titik akhir metrik. Dimensi yang tidak didukung untuk metrik yang ditentukan mengembalikan 400 dengan kode 2001. Lihat Kesalahan Umum.

Kuery Umum

Contoh berikut menunjukkan kueri umum, termasuk metrik yang tersedia di halaman analitik Dasbor Pembuat.

Pendapatan

Kueri pendapatan harian dalam 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"
}'

Retensi D1

Kueri retensi 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"
}'

Pengguna baru vs. pengguna kembali

Kueri DAU yang dipecah menurut pengguna baru vs. pengguna kembali
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"
}'

Agregasi mingguan

Gunakan granularitas yang lebih kasar untuk tampilan jangka panjang dengan lebih sedikit titik data. Dengan granularitas OneWeek, setiap bucket menghitung pengguna yang berbeda selama periode tujuh hari penuh — bukan jumlah nilai harian.

Kueri DAU dengan granularitas mingguan
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"
}'

Pemecahan Top-N

Untuk memberi peringkat satu metrik dan menampilkan yang lain untuk set nilai yang sama, gunakan dua permintaan. Sebagai contoh, untuk melihat konversi pengguna yang membayar untuk 5 negara teratas berdasarkan DAU:

Langkah 1: Temukan nilai dimensi teratas N. Gunakan granularity: "None" untuk satu hasil teragregasi dan limit untuk membatasi jumlah seri yang dikembalikan:

Temukan 5 negara teratas berdasarkan 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
}'

Langkah 2: Kueri metrik tampilan, difilter ke nilai yang dikembalikan pada langkah 1:

Konversi pengguna yang membayar untuk 5 negara teratas
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"
}'

Langkah corong

Corong menunjukkan bagaimana pengguna berkembang melalui urutan langkah yang ditentukan dalam pengalaman Anda. Menanyakan metrik corong memerlukan dua permintaan, karena ID langkahnya bersifat dinamis.

Langkah 1: Temukan langkah corong. Langkah corong hanya muncul dalam hasil untuk hari-hari ketika setidaknya satu pengguna mencapai langkah itu. Menggunakan tampilan yang lebih lama (90 hari adalah default yang aman) memastikan langkah yang sering jarang dicapai masih muncul dalam respons penemuan. Gunakan granularity: "None" untuk mendapatkan satu hasil teragregasi per langkah:

Temukan langkah corong untuk corong Level
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"
}'

Langkah 2: Kueri metrik corong untuk setiap langkah, difilter ke ID langkah yang dikembalikan pada langkah 1:

Tingkat churn pengguna per langkah untuk corong Level
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"
}'

Kesalahan Umum

Sebagian besar kesalahan dikembalikan sebagai kegagalan operasi kueri: tubuh respons menyertakan "done": true dan objek error dengan code numerik dan string message. Kesalahan otentikasi dan sumber daya (401, 404) adalah respons HTTP biasa tanpa envelope tubuh, itulah sebabnya tabel di bawah menunjukkan — untuk kode kesalahan mereka.