Record arbitrary metrics during a live event — participant counts, round completions, score milestones, or any other data you want to track per session. These metrics appear in the Creator Analytics dashboard.
Endpoint
POST /api/v1/runtime/events/{eventId}/usage
Authorization: Bearer <accessToken> (your runtime client token)
| Path param | Description |
|---|
eventId | The event ID returned by Start Event |
Request body
{
"metricType": "participants_joined",
"metricValue": 42
}
| Field | Type | Required | Description |
|---|
metricType | string | ✓ | A label for the metric. Use consistent names across events (e.g. "participants_joined", "rounds_completed", "peak_score") |
metricValue | integer | — | Numeric value for the metric. Omit if you just want to record that an event occurred |
Response
{
"eventId": "evt_xxxxxxxxxxxxxxxx",
"metricType": "participants_joined",
"saved": true
}
Error responses
| Status | Code | Meaning |
|---|
400 | METRIC_TYPE_REQUIRED | metricType was missing or blank |
401 | INVALID_RUNTIME_CLIENT | Token missing or invalid |
403 | USAGE_NOT_AUTHORIZED | Event not found or token not authorized for it |
Example — record participant count
Audience member joins
↓
Increment local participant counter
↓
HTTP POST /runtime/events/{eventId}/usage
{ "metricType": "participant_joined", "metricValue": 1 }
Example — mark a game round
Round ends
↓
HTTP POST /runtime/events/{eventId}/usage
{ "metricType": "round_completed", "metricValue": 3 }
(metricValue = round number)
There is no strict schema for metricType — you define your own labels. Keep them consistent across shows so the analytics dashboard can aggregate them meaningfully.
