Set up RoSession

Quick start

1. Sign in with Roblox and add your game on the dashboard. You get an API key and a guided setup that checks each step live. (During early access, new accounts join a waitlist first.)
2. Insert the module into ServerStorage.
3. Turn on Game Settings › Security › Allow HTTP Requests.
4. Call RoSession.start from a server Script.
5. Press Play. The first session shows up within about 10 seconds.

1. Add the module

Download RoSession.rbxmx. In Roblox Studio, right-click ServerStorage in the Explorer, choose Insert from File… and pick the file. You get a ModuleScript called RoSession with a LocalScript called RoSessionClient inside it.

Leave the LocalScript where it is. When RoSession starts it copies it into StarterPlayerScripts (and into anyone already playing), so it runs on every player's device and reports what the server can't see: FPS, idle time, device and open menus.

2. Allow HTTP requests

RoSession sends data with HttpService, the standard way experiences talk to web services. In Studio, open Home › Game Settings › Security, turn on Allow HTTP Requests and save. Game Settings needs the place to be published once (File › Publish to Roblox).

3. Start RoSession

Add a Script (not a LocalScript) to ServerScriptService and start RoSession with your key:

local RoSession = require(game.ServerStorage.RoSession)

RoSession.start({
    key = "rs_live_…",
    url = "https://www.rosession.com/api/v1/ingest",
})

Call it once, as early as you can, so the first players of every server are recorded. Options:

Studio vs live data

Playtests in Studio are marked as Studio data. They're useful to check your setup but would skew real numbers, so the dashboard hides them unless you flip the Studio data switch. To stop sending from Studio entirely, pass studio = false.

What's tracked automatically

With only RoSession.start, you get:

API reference

Everything is called on the server, after require(game.ServerStorage.RoSession). Calls are cheap: they add to a buffer that's sent every 10 seconds, and never yield or error your code.

boss.Defeated:Connect(function(player, timeTaken)
    RoSession.event(player, "BossDefeated", timeTaken, { boss = boss.Name, difficulty = "Hard" })
end)

RoSession.event(player, "PanelOpened", nil, { "Shop" }) -- "PanelOpened" also feeds the Menus chart

local STEPS = { "Spawned", "Picked a class", "First kill", "Opened shop", "Finished tutorial" }
for i, name in STEPS do
    tutorial.StepReached[i]:Connect(function(player)
        RoSession.funnel(player, "Onboarding", i, name)
    end)
end

RoSession.currency(player, "Coins", 250, "QuestReward")
RoSession.currency(player, "Coins", -1200, "BoughtSword")

local MarketplaceService = game:GetService("MarketplaceService")

MarketplaceService.ProcessReceipt = RoSession.receipts(function(receipt)
    local granted = grantProduct(receipt) -- your code
    return if granted then Enum.ProductPurchaseDecision.PurchaseGranted else Enum.ProductPurchaseDecision.NotProcessedYet
end)

local layout = RoSession.variant(player, "ShopLayout", { "Classic", "Bundles" })
if layout == "Bundles" then
	showBundleShop(player)
end

-- 80% keep the current reward, 20% try the new one
local reward = RoSession.variant(player, "DailyReward", { Coins = 80, Gems = 20 })

Players.PlayerAdded:Connect(function(player)
    local data = loadData(player) -- your DataStore code
    RoSession.loaded(player)
    RoSession.profile(player, { level = data.Level, tutorialStep = data.TutorialStep })
end)

RoSession.activity(player, "Fishing")
RoSession.task(player, "Quest: find the key")
-- later
RoSession.task(player, nil)
RoSession.activity(player, nil)

How leave reasons work

When someone leaves, RoSession sends the signals around their exit. The reason is worked out on our side, so the rules can improve without you updating your game, and the raw signals stay on each session. The first rule that matches wins:

Keys & team access

Each game has its own API keys under Settings. Only a fingerprint of a key is stored, so a key is shown once, when it's created. Make one per place if you like (keys can have labels), and revoke a key to stop it working within a minute.

To share a dashboard, add people by Roblox username in Settings › Who can see this game. They sign in with Roblox and see everything; only the owner can change settings, keys and members. Removing someone takes effect right away.

Discord alerts

In Settings › Discord alerts, paste a channel webhook (in Discord: channel settings › Integrations › Webhooks › New Webhook › Copy Webhook URL) and press Send test. RoSession checks your game every 5 minutes while it sends data, and posts when:

• Player drop: players online fall below half of the last hour's average (when that average is 5+).
• Error spike: 20+ errors in 15 minutes, and 3× the usual rate.
• Crashing servers: 3+ servers stop responding within 15 minutes.
• Leave-reason surge: a leave reason's share of the last 2 hours is double its share of the last week.
• New versions: a new place version starts getting players, and its update impact report a day later.
• Daily summary: yesterday's players, playtime, Robux and top leave reason, at an hour you pick (UTC).

Each alert waits 2 hours before it can post again, so one bad hour is one message. Turn alerts on or off one by one; clear the webhook to stop them all.

Update impact

Every session records the place version it ran on (Roblox bumps it each time you publish). The Update impact page compares a version with the one before it: players per day, session length, sessions per player, bounce rate, new players' day 1 return, paying players, Robux per player and errors per 100 sessions, plus how leave reasons shifted and which errors are new in that version.

Numbers are per player or per session, so a version that ran for a week compares fairly with one that ran for a day, but give a new version a day or two before reading much into it. Old servers keep running the previous version until they restart, so versions overlap for a while.

Why it moved

The Why it moved card on Overview compares the selected period with the one before it (same length) and ranks what most likely explains the change. It looks at:

• Who changed: groups of players (platform, country, join source, new vs returning) that grew or shrank faster than everyone else.
• Why they left: leave reasons whose share went up or down.
• What broke: errors that are new this period, a higher error rate, and servers that crashed.
• What shipped: place versions that went live, and notes on the timeline.
• How it ran: FPS and ping by platform.
• Money: whether Robux moved because of more (or fewer) paying players or how much each one spent, and which products changed most.

Pick Players, Playtime, Length, Robux or Day 1 to explain that number. The player-drop alert and the daily summary on Discord include the top causes too. These are leads to check, not proof: the dashboard pages they link to show the details.

Timeline & notes

Charts on Overview and Daily history show markers for what happened when. RoSession adds new place versions and A/B tests starting on its own; press Add note for anything else (an update, an event, an ad or promo). Anyone who can see the game can add notes. The owner can delete any note, and members can delete their own.

Click a marker, or its chip under the chart, to see what changed in the days after it against the same length of time before it, with the same ranked causes as Why it moved. Use it to check whether an ad, an event or an update actually worked.

Data & privacy

RoSession records gameplay data about your players: Roblox user id, username and display name, account age, Premium, country (from Roblox), device type and screen size, FPS, ping, what they did in your game (events you send, activity, menus) and purchases. It doesn't collect chat, passwords, real names or anything outside your experience, and nothing is sent from players' devices to RoSession directly: the client script reports to your server, which sends one batch every 10 seconds.

Deleting a game in Settings deletes all of its data. See the privacy policy and terms for the details, including your part: telling your players about analytics and following Roblox's terms.

Data retention

Raw data (individual events, server heartbeats and errors) is kept for 30 days by default. Sessions and servers are kept 3× as long, at least 90 days. Daily rollups and per-player totals are kept while the game exists, so Daily history and lifetime numbers don't disappear. Older rows are deleted once a day.

RoSession has a total storage limit. If it gets close, the raw-data window shrinks (never below 7 days) before anything else. Pages that read raw events, like the Event explorer, then only reach back that far.

Limits

• Batches go out every 10 seconds, up to 800 events each. If RoSession can't be reached, up to 3,000 events wait and retry with backoff.
• When a server shuts down, RoSession waits up to 20 seconds to send what's left.
• One request carries up to 1,000 events and 2 MB; each server can send 120 requests a minute.
• Event names are cut to 60 characters and fields to 60; up to 3 fields per event are used for breakdowns.
• During early access: up to 20 games per account, 10 keys and 50 members per game.
• Raw events are kept 30 days by default (see data retention).

Troubleshooting

AI agents & CLI

Ask about your games in plain words from Claude, ChatGPT, Cursor or your terminal. Answers come from your own RoSession data, and every answer links to the dashboard page it came from. Set it up on the AI & CLI page.

• Connector (MCP): add https://www.rosession.com/mcp as a custom connector, then sign in with Roblox and press Allow. Claude Code: claude mcp add --transport http rosession https://www.rosession.com/mcp.
• Command line: npx rosession login, then npx rosession overview "My Game". Pretty in a terminal, JSON when a program runs it (or with --json). npx rosession watch shows live players.
• HTTP: GET https://www.rosession.com/api/agent/<tool>?game=… with Authorization: Bearer rsa_… (make a token on the AI & CLI page). /api/agent/tools lists the tools and their inputs.

Access is read-only and acts as you: it sees the games you can open, and can't change settings, keys, members or notes. Each token or connected app gets 2,000 lookups a day (live doesn't count). Revoke any of them on the AI & CLI page. Every reply looks like this:

{ "status": "ok", "tool": "overview", "game": { "id": "…", "name": "My Game" },
  "period": { "from": "2026-10-12T00:00:00Z", "to": "2026-10-19T00:00:00Z" },
  "data": { "units": "…", … },
  "link": "https://www.rosession.com/dashboard/…",
  "next": [{ "tool": "explain", "input": { "game": "…" }, "command": "rosession explain "My Game"", "when": "Why the numbers moved" }],
  "usage": { "used": 3, "limit": 2000 } }

status is ok or error, with a reason: login_required, not_found, missing_arguments, invalid_arguments, rate_limited or busy. Most tools take game (a name or id), range (24h, 7d, 30d… or from / to) and the dashboard's filters.

HTTP ingest API

The module does all of this for you; it's here if you want to send data from somewhere else.

POST https://www.rosession.com/api/v1/ingest
x-api-key: rs_live_…
Content-Type: application/json

{
  "server": { "id": "<JobId>", "placeId": 123, "placeVersion": 42, "studio": false,
              "private": false, "maxPlayers": 12, "started": 1767225600000 },
  "events": [
    { "t": 1767225601000, "n": "session_start", "u": 1001, "s": "<session id>",
      "d": { "name": "builderman", "display": "builderman" } },
    { "t": 1767225650000, "n": "BossDefeated", "u": 1001, "s": "<session id>",
      "v": 42, "f": ["Golem", "Hard"] }
  ]
}

t is Unix time in milliseconds, n the event name, u the Roblox user id, s your session id. Responses: 200 { ok, accepted }, 401 bad key, 400 bad body, 413 too large, 429 slow down. Built-in event names: