> ## Documentation Index
> Fetch the complete documentation index at: https://xrlive.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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/creator/sales) 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](/sdk/runtime-api/start-event) |

## Request body

```json theme={null}
{
  "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

```json theme={null}
{
  "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)
```

<Note>
  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.
</Note>