Scoring API

Overview

The Scoring API exposes real-time machine-learning endpoints for in-session player-targeting decisions. The first available model is the First-User Payer Conversion scorer — designed to drive the Starter Pack popup decision at the 30-minute post-install mark.

Send six behavioural features from a new install's first 30 minutes, get back a score in [0,1] and a bucket label (top_1pct / top_5pct / top_10pct / rest) for operational thresholding. Fire the popup on top_5pct-or-higher for ~8× lift over base rate.

Authentication

All scoring endpoints require a client-side API key with the scoring:write scope.

First-User Conversion

Predicts the probability that a new install will pay within their first day (D1). Use the bucket label to drive in-session offers like the Starter Pack popup.

curl -X POST class="code-string">"https:class="code-commentclass="code-string">">//api.ilara.ai/v1/scoring/first-user-conversion" \
  -H class="code-string">"X-API-Key: pk_live_v1_xxx" \
  -H class="code-string">"Content-Type: application/json" \
  -d '{
    class="code-string">"devtodev_id": class="code-string">"DCD5D755-E12C-4E3C-9010-CDAE3232B059",
    class="code-string">"loot_distinct_types": 3,
    class="code-string">"sess_duration_total": 500.0,
    class="code-string">"match_avg_fight_time": 45.0,
    class="code-string">"match_wins": 4,
    class="code-string">"install_hour": 14,
    class="code-string">"vpay_count": 2
  }'

{
  class="code-string">"success": true,
  class="code-string">"data": {
    class="code-string">"devtodev_id":     class="code-string">"DCD5D755-E12C-4E3C-9010-CDAE3232B059",
    class="code-string">"score":           0.0823,
    class="code-string">"bucket":          class="code-string">"top_5pct",
    class="code-string">"model_version":   class="code-string">"19423a2fc71c",
    class="code-string">"thresholds_used": {
      class="code-string">"top_1pct":  0.0992,
      class="code-string">"top_5pct":  0.0795,
      class="code-string">"top_10pct": 0.0673
    },
    class="code-string">"scored_at":       class="code-string">"2026-05-20T14:30:00.913Z"
  },
  class="code-string">"error": null,
  class="code-string">"meta":  null
}

Bucket Semantics

Buckets are computed from the model's out-of-fold score distribution and rotate with each retrain. Read thresholds_used from every response — don't hardcode the cutoffs.

Call Timing

The model is trained on features observed in the user's first 30 minutes post-install. Score at 30 minutes (or at end-of-first-session, whichever fires first) for the calibration the model expects.

At 30 minutes, 81% of users (and 92% of payers) have all 6 fields populated. Scoring earlier than 30 minutes is supported but drops ROC-AUC below 0.75 — only do so if the popup must fire in-FTUE.

Model Card

Headline metrics for the current production artifact:

Field-Definition Gotchas

Six places where a backend-side bug will silently send values that don't match what the model was trained on. Confirm each with your engineering team before integration:

• install_hour must be UTC, not IST or device-local. Off-by-5.5h on every score otherwise.
• sess_duration_total uses the activityduration field on session-END events, not wall-clock elapsed time and not the (start_ts, end_ts) difference. activityduration excludes idle.
• match_wins counts the exact uppercase string "WIN". "Win" and "win" are not matched.
• vpay_count covers ALL virtual-currency events (earns + spends of in-game currency), NOT real-money IAPs. Sending IAP-count instead will yield values ~10× smaller than training.
• loot_distinct_types counts distinct values of _LootcaseType. Use the same enumeration as devtodev exports.
• Omit fields you don't have — send 0 if you must, never null. Pydantic strict-types numerics and 422s on null.

Error Responses

Operational Notes

Next Steps

• Authentication — API key types and the scoring:write scope
• Events API — Track behaviour that feeds future scoring models
• Churn Prediction — Complementary lifecycle modelling