> ## 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.

# Start Event

> Open a live session for your visual on the xRLive backend

Starting an event creates a session record on the backend tied to your visual. The returned `eventId` is used in all subsequent calls (join, end, usage).

## Endpoint

```
POST /api/v1/runtime/events/start
```

**Auth:** `Authorization: Bearer <accessToken>` (from [Authenticate](/sdk/runtime-api/authenticate))

## Request body

```json theme={null}
{
  "visualId": "vis_xxxxxxxxxxxxxxxx",
  "runtimeMode": "LIVE"
}
```

| Field         | Type   | Required | Description                                                                  |
| ------------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `visualId`    | string | ✓        | The ID of your visual (visible in the dashboard under your visual's details) |
| `runtimeMode` | string | —        | `"LIVE"` for a real show, `"DEMO"` for testing. Defaults to `"LIVE"`         |

<Note>
  If your Runtime Client credential is already scoped to a specific visual (set at creation time), the `visualId` in the request body can be omitted — it will be inferred from the token.
</Note>

## Response

```json theme={null}
{
  "eventId": "evt_xxxxxxxxxxxxxxxx",
  "status": "ACTIVE",
  "runtimeMode": "LIVE",
  "visualId": "vis_xxxxxxxxxxxxxxxx",
  "concurrencyLimit": 5,
  "activeEventsBeforeStart": 0,
  "startedAt": "2026-04-29T20:00:00Z"
}
```

| Field                     | Description                                                |
| ------------------------- | ---------------------------------------------------------- |
| `eventId`                 | Store this — you'll need it for join, end, and usage calls |
| `status`                  | `"ACTIVE"` — the session is open                           |
| `concurrencyLimit`        | Max simultaneous active events allowed by your plan        |
| `activeEventsBeforeStart` | How many events were already running when this one started |

## Error responses

| Status | Code                            | Meaning                                          |
| ------ | ------------------------------- | ------------------------------------------------ |
| `400`  | `VISUAL_ID_REQUIRED`            | `visualId` missing and not resolvable from token |
| `401`  | `INVALID_RUNTIME_CLIENT`        | Token invalid or expired                         |
| `403`  | `RUNTIME_CLIENT_NOT_AUTHORIZED` | Token not authorized for this visual             |
| `403`  | `CONCURRENCY_LIMIT_REACHED`     | Too many active events for your plan             |

## Blueprint flow

```
Store accessToken (from Authenticate)
    ↓
HTTP POST /runtime/events/start  { visualId, runtimeMode: "LIVE" }
    ↓
Parse response → store eventId
    ↓
Show is running — use eventId for join/end/usage
```