# Test and live mode

> Every key belongs to one project and one mode. Test keys read the simulator; live keys read your paired Cymos.

## Test mode

Test keys (`cym_test_…`) are served by a **simulator** with the same response shapes as a real device. Every response says `meta.livemode: false`, so simulated data can never be mistaken for a reading. Test mode is free and needs no hardware, so you can build and run CI against it.

Each test project starts with simulated rooms such as `room_bedroom`. Test mode covers every capability on this site, including skeletons and telling people from pets, so you can build against any of them before a device is installed.

To work offline, [cymatics mock start](https://docs.cymatics.tech/cli#mock) runs the same simulator on your machine with built-in test keys.

## Scenarios

A scenario is a scripted timeline: someone sleeps, sits up, leaves the bed, falls, recovers. Start one with [POST /v1/scenario-runs](https://docs.cymatics.tech/api/create-scenario-run) and you get a run with its own virtual rooms and devices. Pause it, resume it, or `advance` a paused run by a duration, and read its rooms, results and events like any others. A fixed `seed` replays the same content every time.

The simulator ships with 14 presets:

- continuous\_care\_night
- quiet\_night
- bed\_exit
- fall\_in\_en\_suite
- busy\_meeting\_room
- device\_offline
- person\_and\_pet
- exercise\_and\_skeleton
- vitals\_while\_moving
- quality\_and\_revision
- multi\_device\_tracking
- recovery\_week
- footfall\_and\_visits
- raw\_radar\_sample

`terminal`

```sh
$ echo '{"scenario_id":"bed_exit","seed":42}' | cymatics scenarios run --input -
$ echo '{"action":"pause"}' | cymatics scenario-runs control RUN_ID --input -
$ echo '{"action":"advance","duration_ms":6000}' \
    | cymatics scenario-runs control RUN_ID --input -
$ cymatics events list --room ROOM_ID --json
```

You can also send a custom `timeline` instead of a `scenario_id`. Scenario operations are test only: create scenario run, get scenario run, control scenario run. Live keys calling them get `403 mode_mismatch`.

## Live mode

Live keys (`cym_live_…`) read from a **paired Cymo**. You can only create one after pairing a device in the dashboard. Live usage is billed per live hour: one hour of streaming from one Cymo.

Live keys call the same endpoints and get the same shapes, with `meta.livemode: true`. What a live project measures depends on the Cymos paired to it: [List capabilities](https://docs.cymatics.tech/api/list-capabilities) reports `live_available` for each capability, and [List models](https://docs.cymatics.tech/api/list-models) lists the models your live project can use.

An operation with no live data for the project, for example because no paired Cymo covers it, returns `503 live_unavailable` rather than made-up data. Once a project has a monthly live-hour cap and reaches it, live requests get `429 quota_exceeded` until the cap is raised.

## Switching modes

Use the test and live switch in the dashboard breadcrumb. Your code does not change: swap the key and the API answers in that key's mode. A flag can't turn a test key into a live one, and a live key never reads simulated data.