5.4 Alert Detection & Settings
Section 5 — Quotas & Alerts
5.4 Alert Detection & Settings
Alerts and notifications help workspace and tenant admins notice unusual traffic and rate-limit pressure before they become operational problems.
This page uses these terms consistently:
| Term | Meaning |
|---|---|
| Alerts | Platform-wide traffic warnings for unusual request volume or large payloads |
| Notifications | User-facing messages about a specific key or threshold |
| Enforcement | A rate-limit decision that can reject traffic with 429 |
There are two related systems:
| System | What it watches | Who receives it |
|---|---|---|
| Alerts | Short traffic spikes from Tenant API Keys (X-API-Key) or Game Auth Keys (X-Game-Key) | Platform admins and tenant owners/admins |
| Game Auth Key (X-Game-Key) rate-limit notifications | A game write key approaching or reaching its own minute/hour limit | Tenant owners/admins |
Both systems are informational. The only thing that rejects traffic with a 429 is an enforced key rate limit (see 5.4.2). Alerts and notifications explain what is happening; they never block requests or change limits.
5.4.1 Alerts
Alerts are operational warnings. They are useful for detecting unexpected bursts, accidental loops, unusually large uploads, or possible abuse. Both Tenant API Keys (X-API-Key) and Game Auth Keys (X-Game-Key) can create alerts.
There are two alert types: rate alerts, triggered by request volume in a one-minute window, and payload alerts, triggered by inbound bytes in a one-minute window. The thresholds for both are shown below.
Alert Settings
| Setting | Default | Meaning |
|---|---|---|
RateLimitPerMinute | 300 | A rate alert is created when a key reaches this many requests in one minute |
PayloadBytesPerMinute | 5,000,000 | A payload alert is created when inbound request bytes reach this value in one minute |
SuppressionMinutes | 10 | Repeat alerts for the same key and alert type are suppressed during this window |
These settings are platform-wide. Tenant and workspace admins receive alerts and can manage tenant-scoped alert webhooks, but thresholds cannot be customized per tenant or per key.
How Alert Detection Works
| Key type | Typical role | Detection timing |
|---|---|---|
| Tenant API Keys (X-API-Key) | Read/API access for dashboards, internal tools, and third-party integrations | Near real time, after each request |
| Game Auth Keys (X-Game-Key) | Write-side game or trusted server traffic into Gamers Lab for a tenant | Batch processed about once per minute |
Suppression applies per key and alert type. A rate alert on one key does not suppress alerts on another key, even within the same tenant.
Payload alert detection uses the request Content-Length value. Requests without a known inbound size may be skipped for payload byte tracking.
Alert Delivery
When a new alert is created, the platform sends it through the available alert channels:
| Channel | What happens |
|---|---|
| In-app notification | Created for platform admins and the tenant's owner/admin members |
| Sent to the same alert audience where email delivery is available | |
| Webhook | Queued for active platform webhooks and active tenant-scoped webhooks for the affected tenant |
Tenant owners/admins can use tenant-scoped webhooks to forward alert events to their own monitoring or incident tools.
5.4.2 Tenant API Key Rate Limits
Tenant API Keys (X-API-Key) are read/API access keys, commonly used by dashboards, internal tools, backend services, and third-party integrations that read or stream tenant data from Gamers Lab.
Each Tenant API Key has enforced per-key rate limits:
| Limit | Default | What happens when exceeded |
|---|---|---|
| Per-minute rate limit | 60 requests/minute | Requests are rejected with 429 Too Many Requests |
| Per-hour rate limit | 1,000 requests/hour | Requests are rejected with 429 Too Many Requests |
These defaults can be configured per tenant or per key.
Subscriber accounts can also use Tenant API Keys once they have active access to a tenant's data. Subscriber keys use the same header, key family, and default limits; the only difference is that they are owned by the subscriber workspace rather than the studio workspace.
5.4.3 Game Auth Key Rate-Limit Notifications
Game Auth Keys (X-Game-Key) are write-side keys used by games or trusted game servers to send tenant gameplay data into Gamers Lab.
Each Game Auth Key has enforced per-key rate limits:
| Limit | Default | What happens when exceeded |
|---|---|---|
| Per-minute rate limit | 10,000 requests/minute | Requests are rejected with 429 Too Many Requests |
| Per-hour rate limit | 46,000 requests/hour | Requests are rejected with 429 Too Many Requests |
For /api/game/* write traffic, tenant owners/admins receive tenant-scoped notifications when a Game Auth Key reaches two thresholds:
| Threshold | Meaning |
|---|---|
| 75% | The key is approaching its configured minute or hour rate limit |
| 100% | The key has reached its configured minute or hour rate limit |
By default, the 75% and 100% notifications are based on the 10,000/minute and 46,000/hour limits unless the key is configured differently.
These notifications help admins spot keys that may need traffic changes, batching improvements, or a limit review. Like alerts, they are suppression-gated, so sustained traffic does not create a new notification on every request.
5.4.4 Practical Admin Guidance
| If you see... | Check... |
|---|---|
| A rate alert | Which Tenant API Key (X-API-Key) or Game Auth Key (X-Game-Key) generated the burst and whether traffic is expected |
| A payload alert | Whether clients are sending unusually large request bodies |
A Tenant API Key (X-API-Key) 429 | Whether the key exceeded its per-minute or per-hour rate limit |
| A 75% Game Auth Key (X-Game-Key) rate-limit notification | Whether the key is nearing its normal traffic ceiling |
A 100% Game Auth Key (X-Game-Key) rate-limit notification or 429 responses | Whether callers should reduce frequency, batch differently, or request a limit review |