Players are pseudonymous: pid is 64 hex characters. Names appear only if the organisation shows names and the token's role may see them. Player routes need permission to read players.
| Route | Returns |
|---|---|
/orgs/<org>/players | Players (server, limit, before to page) |
/orgs/<org>/players/<pid> | One player's profile |
/orgs/<org>/players/<pid>/timeline | Their merged history |
/orgs/<org>/players/<pid>/cards | Their money and punishment record over 30 days |
/orgs/<org>/players/<pid>/attribution | Their first-touch attribution |
/orgs/<org>/insights/top-players | Most active players |
/orgs/<org>/insights/retention | Day 1, 7 and 30 retention |
/orgs/<org>/insights/lag-spikes | Lag spikes by cause |
/orgs/<org>/insights/cohorts?weeks=8 | Weekly cohorts: day-1, 7, 30 return and W1 to W7 |
/orgs/<org>/insights/churn?limit=10 | Churn-risk scores with reasons; &pid= for one player |
/orgs/<org>/insights/countries | Joins, day-7 return and revenue by country |
/orgs/<org>/insights/forecast?metric=players | Next 14 days with an 80% band (players or revenue) |
All insights routes take server, from and to where it makes sense and omit server for the whole organisation.
Top players
GET /orgs/<org>/insights/top-players?by=playtime&limit=10 (by is playtime or sessions, limit up to 50):
{"from":"...","to":"...","history_limit":null,"server_id":null,"by":"playtime",
"totals":{"players":1204,"sessions":9310},
"players":[{"pid":"9f2c...","name":null,"sessions":41,"playtime_s":93211,"servers":2,"first_seen":"...","last_seen":"..."}]}Retention
{"sessions":9310,"unique_players":1204,"avg_session_s":2411,"median_session_s":1620,"new_players":311,"returning_players":893,
"retention":{"d1":{"rate":0.41,"eligible":280,"returned":115},"d7":{"rate":0.22,"eligible":190,"returned":42},"d30":{"rate":0.11,"eligible":60,"returned":7}},
"by_day":[{"day":"2026-10-05","players":410,"new_players":38}],"history_limit":null}Day-N retention counts new players whose window has fully passed, so eligible is smaller than new_players.
Lag spikes
Returns spikes, worst_tick_ms, avg_tick_ms, by_cause (cause, spikes, avg_share_pct, worst_tick_ms), by_server, by_day and the 10 most recent.
Forecast
{status: "ok" | "insufficient", days_available, days_needed: 21, history[], forecast: [{day, mean, lo, hi}], method, backtest_mape}. It needs 21 days of data and is computed per request.