Roblox Analytics Query

An unofficial, dependency-free Python client for the Roblox Open Cloud Analytics Query API.

The API is currently in beta. Metric names, supported dimensions, granularities and retention windows are defined by Roblox and may change.

Requirements

• Python 3.11 or newer
• A Roblox Open Cloud key scoped to the target experience with:

System: universe-analytics
Operation: universe.analytics:read

Do not expose the key in a Roblox client or commit it to source control.

Installation

python -m pip install "git+https://github.com/kentiq/roblox-analytics-query.git"

Set the key in the environment:

export ROBLOX_ANALYTICS_API_KEY="..."

PowerShell:

$env:ROBLOX_ANALYTICS_API_KEY = "..."

Library usage

from roblox_analytics import AnalyticsClient

client = AnalyticsClient.from_env()

result = client.query_metric(
    1234567890,
    metric="DailyActiveUsers",
    granularity="OneDay",
    start_time="2026-07-01T00:00:00Z",
    end_time="2026-07-24T00:00:00Z",
)

result.write_csv("dau.csv")
result.write_json("dau.json")

Breakdowns and filters follow the Open Cloud request schema:

result = client.query_metric(
    1234567890,
    metric="DailyActiveUsers",
    granularity="OneDay",
    start_time="2026-07-01T00:00:00Z",
    end_time="2026-07-24T00:00:00Z",
    breakdown=["Platform"],
    filters=[
        {
            "dimension": "Country",
            "values": ["US", "GB"],
            "operation": "In",
        }
    ],
)

Discover values accepted by a dimension:

result = client.query_dimension_values(
    1234567890,
    metric="DailyActiveUsers",
    dimensions=["Country"],
    start_time="2026-07-01T00:00:00Z",
    end_time="2026-07-24T00:00:00Z",
)

print(result.dimension_values())

The client polls long-running operations automatically. Poll interval and timeout can be set on AnalyticsClient.

Command line

Query a metric and write CSV:

roblox-analytics metric \
  --universe-id 1234567890 \
  --metric DailyActiveUsers \
  --granularity OneDay \
  --start 2026-07-01T00:00:00Z \
  --end 2026-07-24T00:00:00Z \
  --output dau.csv \
  --format csv

Query dimension values:

roblox-analytics dimension-values \
  --universe-id 1234567890 \
  --metric DailyActiveUsers \
  --dimension Country \
  --start 2026-07-01T00:00:00Z \
  --end 2026-07-24T00:00:00Z

Without --output, JSON is written to standard output.

Result handling

AnalyticsResult.to_dict() returns the complete operation envelope from Roblox. Metric results can also be flattened with rows(), to_csv() or write_csv().

Query windows use RFC 3339 timestamps. start_time is inclusive, end_time is exclusive, and Roblox buckets results in UTC.

Roblox may omit buckets with no returned data. This client preserves the API response and does not infer missing values. Build the requested time range explicitly if a continuous series is required.

For text-valued metrics, stringValues is retained in JSON and encoded as a JSON array in CSV. The optional data-point status field is also preserved.

Errors

HTTP, operation, protocol and polling timeout failures use separate exception types exported from roblox_analytics. Error messages never include the API key.

The client does not retry rejected queries automatically. In particular, a 429 response can indicate that the analytics point budget was exceeded, in which case the query should be reduced rather than repeated unchanged.

Roblox currently documents a limit of 30 initial queries per minute per API-key owner and 3,000 polling requests per minute per owner.

API documentation

• Analytics guide
• Analytics API reference
• Supported metrics and dimensions

License

MIT