Record Usage

Push custom metrics to the backend during an active event

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

Auth: 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.