# Get a recording (https://orgasm.dev/docs/api/recordings/getRecording)

# Get a recording

- **Method:** `GET`
- **Path:** `/v1/recordings/{recordingId}`
- **Operation ID:** `getRecording`
- **Tags:** recordings

Returns the recording's status and progress and, once `completed`, its
`result`: the subject read, a summary of each orgasm, and the timeline
of discrete events. Imminence, sampled every second, is in
`listRecordingEvents`.

## Effective servers

- `https://orgasm.dev`

  `sk_test_` keys reach the sandbox. `sk_live_` keys are refused until live analysis is available.
- `http://localhost:3000`

  The docs site running locally (`npm run dev`), which serves the sandbox.
- `http://localhost:4010`

  The standalone sandbox (`npm run mock`), which also serves the WebSocket channel.

## Authentication

- **secretKey**: HTTP bearer (`sk_test_… or sk_live_…`)

  A secret key, sent as `Authorization: Bearer sk_test_…`. Keep it on your server. Test keys reach the sandbox; live keys reach live analysis. In the sandbox any key that starts with `sk_test_` works.

## Path parameters

- **`recordingId` (required)**: `string`, pattern: `^rec_[0-9a-z]{20}$`

  The recording's `id`.

  **Example:**

  ```json
  "rec_2n5v8c1x4m7q0w3e6r9t"
  ```

## Responses

### 200 The recording.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

schema: `Recording`

One recorded video, from submission to its result.

- **`clientReferenceId` (required)**: `string | null`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

  The `clientReferenceId` it was submitted with, or `null`.
- **`completedAt` (required)**: `string | null`, format: `date-time`
- **`createdAt` (required)**: `string`, format: `date-time`
- **`failure` (required)**: `object | null`, schema: `RecordingFailedData`

  Present once `status` is `failed`.
  - **`code` (required)**: `string`, possible values: `"unreadable_media", "no_face", "too_short", "too_long", "fetch_failed", "upload_expired", "internal"`

    `unreadable_media`: the file could not be decoded (H.264 or H.265 video is required). `no_face`: no face was visible long enough to analyse. `too_short`: under two minutes. `too_long`: over four hours. `fetch_failed`: `source.url` could not be fetched. `upload_expired`: the upload URL expired before a file arrived. `internal`: an internal failure; submit it again.
  - **`message` (required)**: `string`
- **`id` (required)**: `string`, pattern: `^rec_[0-9a-z]{20}$`
- **`inputs` (required)**: `object`
  - **`audio` (required)**: `boolean`
  - **`body` (required)**: `boolean`
- **`metadata` (required)**: `object`, schema: `Metadata`, maxProperties: `20`

  Up to 20 string values of your own, returned on the object and on its charges, where they break your costs down (a plan, a product, a region, a campaign). Do not put personal data in it: a person's pseudonymous id goes in `userReference`.

  **Additional properties:**

  `string`, maxLength: `500`
- **`mode` (required)**: `string`, possible values: `"test", "live"`
- **`object` (required)**: `string`, const: `"recording"`
- **`progress` (required)**: `object | null`

  How far processing has got, while `processing`.
  - **`durationS` (required)**: `number | null`
  - **`processedS` (required)**: `number`
- **`result` (required)**: `object | null`, schema: `RecordingResult`

  Present once `status` is `completed`.
  - **`subject` (required)**: `object | null`, schema: `SubjectIdentifiedData`
    - **`decidedAtS` (required)**: `number`

      When the read was made, in stream seconds.
    - **`detectors` (required)**: `array`, minItems: `1`, uniqueItems: `true`

      The detectors that apply from now on. A hint decides them when given; otherwise the read does; while undetermined, all of them run and their calls arrive with `confidence: low`.

      **Items:**

      `string`, possible values: `"onset_end", "peak", "face_end"`

      Which detector made a call. `onset_end` calls the start and the end of an orgasm and applies to women. `peak` calls a single peak and applies to men. `face_end` calls the end of a man's orgasm from the face alone.
    - **`hint` (required)**: `string | null`, possible values: `"woman", "man", null`

      The `subjectHint` you gave when you created the session, or `null`.
    - **`pWoman` (required)**: `number | null`, minimum: `0`, maximum: `1`

      The read's probability that the face is a woman's, or `null` when the face could not be read.
    - **`secondsObserved` (required)**: `integer`, minimum: `0`, maximum: `30`

      Seconds of visible face the read was made from (at most 30).
    - **`sex` (required)**: `string`, possible values: `"woman", "man", "undetermined"`

      Whether the face reads as a woman's or a man's, which decides the detectors that apply. `undetermined` is common: the read is made once, from the first 30 seconds of visible face, and only decides when it is clear. It is an estimate for choosing detectors, not a statement about the person's sex or gender identity.
  - **`summary` (required)**: `object`
    - **`durationS` (required)**: `number`
    - **`orgasmCount` (required)**: `integer`, minimum: `0`
    - **`orgasms` (required)**: `array`

      **Items:**

      schema: `OrgasmSummary`

      One orgasm in a recording, assembled from its calls.
      - **`confidence` (required)**: `string | null`, possible values: `"high", "medium", "low", null`

        How complete the input behind this event was. `high`: the face was tracked throughout the window the signal reads and every input it uses was present. `medium`: an input was missing or partial for part of that window. `low`: the event rests on degraded input, or comes from a detector that ran while the subject was undetermined. `null` on events that are not signals (`session.status`, `input.warning`, `recording.*`). Confidence describes the input, not a calibrated probability that the event is right.
      - **`detectors` (required)**: `array`

        **Items:**

        `string`, possible values: `"onset_end", "peak", "face_end"`

        Which detector made a call. `onset_end` calls the start and the end of an orgasm and applies to women. `peak` calls a single peak and applies to men. `face_end` calls the end of a man's orgasm from the face alone.
      - **`durationS` (required)**: `number | null`
      - **`endAtS` (required)**: `number | null`
      - **`onsetAtS` (required)**: `number | null`
      - **`orgasmIndex` (required)**: `integer`, minimum: `1`
      - **`peakAtS` (required)**: `number | null`
  - **`timeline` (required)**: `array`

    The discrete events, in order: orgasm calls, the subject read and input warnings. Imminence is in `listRecordingEvents`.

    **Items:**

    **One of:** discriminated by `type`
    - **All of:**, type: `imminence.updated`
      - **One of:**
        - `object`
        - `object`

        `object`, schema: `EventBase`

        The envelope every event shares, on every channel: the stream, the socket, webhooks and the event lists. Unknown fields may be added; ignore them.
        - **`confidence` (required)**: `string | null`, possible values: `"high", "medium", "low", null`

          How complete the input behind this event was. `high`: the face was tracked throughout the window the signal reads and every input it uses was present. `medium`: an input was missing or partial for part of that window. `low`: the event rests on degraded input, or comes from a detector that ran while the subject was undetermined. `null` on events that are not signals (`session.status`, `input.warning`, `recording.*`). Confidence describes the input, not a calibrated probability that the event is right.
        - **`data` (required)**: `object`

          The event's own fields; see each event type.
        - **`id` (required)**: `string`, pattern: `^evt_[0-9a-z]{20}$`

          Unique and stable. A redelivered event carries the same `id`, so deduplicate on it.
        - **`mode` (required)**: `string`, possible values: `"test", "live"`

          `test` for sandbox events, `live` for live analysis.
        - **`object` (required)**: `string`, const: `"event"`
        - **`sequence` (required)**: `integer`, minimum: `1`

          Position of the event in its session or recording, starting at 1 and increasing by one. Use it to order events and to notice a gap.
        - **`streamTimeS` (required)**: `number`, minimum: `0`

          When the event was produced, in seconds on the media's own clock (time since the first frame of the live stream, or time into the recording). For an orgasm call this is the moment the call was made, which is later than the moment it names (`data.eventAtS`).
        - **`type` (required)**: `string`, possible values: `"imminence.updated", "signals.updated", "stimulation.updated", "orgasm.onset", "orgasm.peak", "orgasm.end", "edge.completed", "subject.identified", "session.status", "input.warning", "recording.completed", "recording.failed"`

          The kind of event. New types can be added at any time; ignore a type you do not recognise rather than failing.
        - **`wallTime` (required)**: `string`, format: `date-time`

          When the event was produced, as UTC wall-clock time. For recordings it is when the analysis made the call, not a time in the recording.
        - **`recordingId`**: `string`, pattern: `^rec_[0-9a-z]{20}$`

          The recording the event belongs to. Absent on live-session events.
        - **`sessionId`**: `string`, pattern: `^ls_[0-9a-z]{20}$`

          The live session the event belongs to. Absent on recording events.
      - `object`
        - **`data` (required)**: `object`, schema: `ImminenceData`
          - **`baselineReady` (required)**: `boolean`

            Whether the person's own resting baseline is in. It takes about a minute of visible face after the stream starts; imminence is `null` before.
          - **`faceVisible` (required)**: `boolean`

            Whether a face was tracked in the last second.
          - **`featuresPresent` (required)**: `number`, minimum: `0`, maximum: `1`

            Share of the model's inputs that were available this second, from 0 to 1. Lower values mean the face was turned away, occluded or too far for part of the second.
          - **`logit30` (required)**: `number | null`

            `p30` as a logit, ln(p / (1 - p)). Add your own prior on this scale to combine it with what your product knows.
          - **`logit60` (required)**: `number | null`

            `p60` as a logit.
          - **`p30` (required)**: `number | null`, minimum: `0`, maximum: `1`

            Probability that the next orgasm begins within 30 seconds, given that it has not begun yet (the onset for a woman, the peak for a man). A probability over a horizon, not a countdown. `null` while the face is not visible or its baseline is not ready.
          - **`p60` (required)**: `number | null`, minimum: `0`, maximum: `1`

            The same probability over 60 seconds. Never lower than `p30`.
          - **`recentCalls` (required)**: `array`, maxItems: `8`

            The last orgasm calls of the session, oldest first, at most eight, repeated in every update so that a call whose own event you missed is still seen within a second.

            **Items:**

            schema: `RecentCall`

            An orgasm call, as repeated in every `imminence.updated`.
            - **`eventAtS` (required)**: `number`

              The moment the call names, in stream seconds.
            - **`id` (required)**: `string`, pattern: `^evt_[0-9a-z]{20}$`

              The `id` of the call's own event.
            - **`type` (required)**: `string`, possible values: `"orgasm.onset", "orgasm.peak", "orgasm.end"`
          - **`stimulationAware` (required)**: `boolean`

            Whether you have reported stimulation for this session (see `reportStimulation`). When `true`, imminence also accounts for how long the person has been stimulated; when `false`, it reads the face alone.
        - **`type` (required)**: `string`, const: `"imminence.updated"`

      schema: `ImminenceUpdatedEvent`

      About once a second while the face is analysed: the probability that the next orgasm begins within 30 and 60 seconds. Streamed only; never sent to webhooks.
    - **All of:**, type: `signals.updated`
      - *Schema `EventBase` is shown above.*
      - `object`
        - **`data` (required)**: `object`, schema: `SignalsData`

          The body's other signals, as a heads-up display shows them. Each is `null` while its input is absent or still calibrating; none is a call, and none is charged.
          - **`contractionsPerMin` (required)**: `number | null`, minimum: `0`

            Pelvic floor contractions a minute, from the body view; null without it.
          - **`face` (required)**: `object | null`, schema: `FaceChannels`

            The face's expression channels and the head's turn, once a second, for a display that draws a face; `face.frame` carries the same about five times a second to readers that ask. Null while the face is out of view or before the baseline is in. A view token reads it only when made with `includeFace`.
            - **`expression` (required)**: `object`, schema: `FaceExpression`

              The face's expression as 24 channels, each from 0 (as at the person's own rest) to 1 (a full movement). Names ending in `L` and `R` are the person's own left and right. Channels may be added; draw the ones you know.
              - **`browDownL` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`browDownR` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`browInnerUp` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`browOuterUpL` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`browOuterUpR` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`browTogether` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`cheekSquintL` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`cheekSquintR` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`chinRaise` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`eyeBlinkL` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`eyeBlinkR` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`eyeWideL` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`eyeWideR` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`jawOpen` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`lidRaise` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`lidTighten` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`lipsPart` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`mouthPucker` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`mouthSmileL` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`mouthSmileR` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`mouthStretch` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`noseFlare` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`noseSneer` (required)**: `number`, minimum: `0`, maximum: `1`
              - **`noseWrinkle` (required)**: `number`, minimum: `0`, maximum: `1`

              **Additional properties:**

              `number`, minimum: `0`, maximum: `1`
            - **`head` (required)**: `object`, schema: `HeadPose`

              How far the head has turned from the person's own resting pose, in degrees, as someone facing them sees it.
              - **`pitchDeg` (required)**: `number`, minimum: `-90`, maximum: `90`

                Positive raises the chin; negative lowers it.
              - **`rollDeg` (required)**: `number`, minimum: `-90`, maximum: `90`

                Positive tips the top of the head toward the viewer's right.
              - **`yawDeg` (required)**: `number`, minimum: `-90`, maximum: `90`

                Positive turns the face toward the viewer's right, the person's own left.
          - **`faceRegions` (required)**: `object | null`, schema: `FaceRegions`

            Null while the face is out of view or before the baseline is in.
            - **`brows` (required)**: `number`, minimum: `0`, maximum: `1`
            - **`cheeks` (required)**: `number`, minimum: `0`, maximum: `1`
            - **`corners` (required)**: `number`, minimum: `0`, maximum: `1`
            - **`eyes` (required)**: `number`, minimum: `0`, maximum: `1`
            - **`jaw` (required)**: `number`, minimum: `0`, maximum: `1`
            - **`lips` (required)**: `number`, minimum: `0`, maximum: `1`
            - **`nose` (required)**: `number`, minimum: `0`, maximum: `1`
          - **`loudnessAboveBaselineDb` (required)**: `number | null`

            How much louder the voice is than at the baseline, in decibels; null without the microphone or before its baseline.
          - **`movement` (required)**: `string | null`, possible values: `"settled", "shifting", "unsettled", null`

            How still the body is, from the body view; null without it.
          - **`vocalizationsPerMin` (required)**: `number | null`, minimum: `0`

            Vocalizations a minute, from the microphone; null without it.
        - **`type` (required)**: `string`, const: `"signals.updated"`

      schema: `SignalsUpdatedEvent`

      Once a second with each `imminence.updated` of a live session: the vocalization rate and loudness from the microphone, the contraction rate and movement from the body view, and how far each region of the face has moved from the baseline. For a heads-up display; not a call, and never charged. Streamed only; never sent to webhooks.
    - **All of:**, type: `stimulation.updated`
      - *Schema `EventBase` is shown above.*
      - `object`
        - **`data` (required)**: `object`, schema: `StimulationData`

          The stimulation your product last reported, merged across its reports: a report updates the fields it carries and keeps the rest. Fields your product never reported are null.
          - **`changedAtS` (required)**: `number`, minimum: `0`

            When the change happened, in stream seconds. The event's own `streamTimeS` is when orgasm.dev received the report, which can be later.
          - **`channels` (required)**: `array | null`, maxItems: `4`

            Each output's level, for a device with more than one.

            **Items:**

            schema: `StimulationChannel`

            One output of a device with more than one, such as an e-stim unit's channels.
            - **`id` (required)**: `string`, pattern: `^[a-z0-9]{1,8}$`

              The output's name, such as `a` or `b`.
            - **`level` (required)**: `number`, minimum: `0`

              The output's level now, on the device's own scale.
            - **`levelMax` (required)**: `number | null`, exclusiveMinimum: `0`

              The highest level the output will go to now, on the same scale; null when your product did not say.
          - **`device` (required)**: `object | null`, schema: `StimulationDevice`

            The device your product drives, as a display names it.
            - **`connected` (required)**: `boolean`

              False while your product cannot reach the device; a display shows it as disconnected.
            - **`label` (required)**: `string | null`, maxLength: `40`

              What a display calls the device, such as `Wand` or `Unit`; null when your product did not say. Never the person's name.
          - **`drive` (required)**: `string | null`, possible values: `"auto", "manual", "hold", "paused", null`

            Who sets the level: `auto` (your product, following the person's signals), `manual` (the person's own hand), `hold` (held where it is) or `paused`.
          - **`intensity` (required)**: `number | null`, minimum: `0`, maximum: `1`

            The intensity from 0 to 1 on your product's own scale.
          - **`level` (required)**: `number | null`, minimum: `0`

            The device's level on its own scale, such as 0 to 100.
          - **`levelMax` (required)**: `number | null`, exclusiveMinimum: `0`

            The highest level the device will go to now, on the same scale.
          - **`mode` (required)**: `string | null`, maxLength: `40`

            The device's mode or pattern, as your product names it.
          - **`modeLabel` (required)**: `string | null`, maxLength: `40`

            The mode's name to show; without it a display shows `mode` in words.
          - **`state` (required)**: `string`, possible values: `"on", "off"`

            Whether stimulation is on or off.
        - **`type` (required)**: `string`, const: `"stimulation.updated"`

      schema: `StimulationUpdatedEvent`

      Each time your product reports stimulation, through `reportStimulation` or a `stimulation` message on the socket: the device's state, level, channels and mode as reported, for a display beside the person's signals. At most four a second; reports in between are merged into the next. Streamed only; never sent to webhooks.
    - **All of:**, type: `orgasm.onset`
      - *Schema `EventBase` is shown above.*
      - `object`
        - **`data` (required)**: `object`, schema: `OrgasmOnsetData`
          - **`calledAtS` (required)**: `number`

            The moment the detector made the call, in stream seconds.
          - **`detector` (required)**: `string`, const: `"onset_end"`
          - **`eventAtS` (required)**: `number`

            The moment the orgasm began, in stream seconds.
          - **`lagS` (required)**: `number`, minimum: `0`

            `calledAtS - eventAtS`: how late the call is.
          - **`orgasmIndex` (required)**: `integer`, minimum: `1`

            Which orgasm of the session this is, from 1. The onset and the end of the same orgasm share it.
          - **`score` (required)**: `number`, minimum: `0`, maximum: `1`

            The detector's score for the call, on the scale of `threshold`.
          - **`threshold` (required)**: `number`, minimum: `0`, maximum: `1`

            The level the detector calls at. A score at or above it made the call.
        - **`type` (required)**: `string`, const: `"orgasm.onset"`

      schema: `OrgasmOnsetEvent`

      An orgasm began. Applies to women (the `onset_end` detector). Requires the microphone. The call arrives a few seconds after the moment it names.
    - **All of:**, type: `orgasm.peak`
      - *Schema `EventBase` is shown above.*
      - `object`
        - **`data` (required)**: `object`, schema: `OrgasmPeakData`
          - **`calledAtS` (required)**: `number`

            The moment the detector made the call, in stream seconds.
          - **`detector` (required)**: `string`, const: `"peak"`
          - **`eventAtS` (required)**: `number`

            The moment of the peak, in stream seconds.
          - **`lagS` (required)**: `number`, minimum: `0`

            `calledAtS - eventAtS`.
          - **`orgasmIndex` (required)**: `integer`, minimum: `1`

            Which orgasm of the session this is, from 1. The peak and the face-based end of the same orgasm share it.
          - **`score` (required)**: `number`, minimum: `0`, maximum: `1`
          - **`threshold` (required)**: `number`, minimum: `0`, maximum: `1`
        - **`type` (required)**: `string`, const: `"orgasm.peak"`

      schema: `OrgasmPeakEvent`

      The peak of an orgasm. Applies to men (the `peak` detector). Requires the microphone. The call arrives a few seconds after the moment it names.
    - **All of:**, type: `orgasm.end`
      - *Schema `EventBase` is shown above.*
      - `object`
        - **`data` (required)**: `object`, schema: `OrgasmEndData`
          - **`calledAtS` (required)**: `number`

            The moment the detector made the call, in stream seconds.
          - **`detector` (required)**: `string`, possible values: `"onset_end", "face_end"`
          - **`durationS` (required)**: `number`, minimum: `0`

            `eventAtS - startedAtS`.
          - **`eventAtS` (required)**: `number`

            The moment the orgasm ended, in stream seconds.
          - **`lagS` (required)**: `number`, minimum: `0`

            `calledAtS - eventAtS`.
          - **`orgasmIndex` (required)**: `integer`, minimum: `1`

            Which orgasm of the session ended.
          - **`ruined` (required)**: `boolean`

            Whether the orgasm was ruined: the last stimulation report before it began was `off`, sent within the 30 seconds before while `p30` was at 0.75 or above (the ruin preset's stop). Charged as a ruin, at the price of an orgasm. Always `false` for a recording, which takes no stimulation reports.
          - **`score` (required)**: `number | null`, minimum: `0`, maximum: `1`

            The detector's score, or `null` for `face_end`, which has none.
          - **`startedAtS` (required)**: `number`

            When the same orgasm began: its onset (`onset_end`) or its peak (`face_end`).
          - **`threshold` (required)**: `number | null`, minimum: `0`, maximum: `1`

            The detector's calling level, or `null` for `face_end`.
        - **`type` (required)**: `string`, const: `"orgasm.end"`

      schema: `OrgasmEndEvent`

      An orgasm ended. For women it closes the orgasm an `orgasm.onset` opened (`onset_end`, requires the microphone); for men it follows an `orgasm.peak` and is read from the face (`face_end`).
    - **All of:**, type: `edge.completed`
      - *Schema `EventBase` is shown above.*
      - `object`
        - **`data` (required)**: `object`, schema: `EdgeCompletedData`
          - **`durationS` (required)**: `number`, minimum: `0`

            `eventAtS - startedAtS`.
          - **`edgeIndex` (required)**: `integer`, minimum: `1`

            Which edge of the session this is, from 1.
          - **`eventAtS` (required)**: `number`

            When `p30` fell back below 0.3, the preset's resume level, which made the approach an edge, in stream seconds.
          - **`peakP30` (required)**: `number`, minimum: `0.6`, maximum: `1`

            The highest `p30` of the approach.
          - **`startedAtS` (required)**: `number`

            When `p30` reached 0.6, the edge preset's back-off level, in stream seconds.
        - **`type` (required)**: `string`, const: `"edge.completed"`

      schema: `EdgeCompletedEvent`

      An edge: imminence (`p30`) reached 0.6 and fell back below 0.3 with no orgasm called in between. orgasm.dev counts it on its side, as the edge preset's back-off and resume levels, and charges half a credit for it in live mode. Sent with the reading that completed it; its `confidence` is the lowest of the approach's readings. Without the microphone no orgasm can be called, so every approach that recedes is an edge.
    - **All of:**, type: `subject.identified`
      - *Schema `EventBase` is shown above.*
      - `object`
        - **`data` (required)**: `object`, schema: `SubjectIdentifiedData`

          *Schema `SubjectIdentifiedData` is shown above.*
        - **`type` (required)**: `string`, const: `"subject.identified"`

      schema: `SubjectIdentifiedEvent`

      Once per session or recording, after about 30 seconds of visible face: whether the face reads as a woman's or a man's, and which detectors apply from then on.
    - **All of:**, type: `session.status`
      - *Schema `EventBase` is shown above.*
      - `object`
        - **`data` (required)**: `object`, schema: `SessionStatusData`
          - **`degraded` (required)**: `boolean`

            An input the session declared is missing, or the face is not visible. The open `input.warning` events say which.
          - **`endedReason` (required)**: `string | null`, possible values: `"client_ended", "media_ended", "media_timeout", "max_duration", "interrupted", "policy", "error", null`

            Why the session ended, once `status` is `ended`. `client_ended`: you ended it. `media_ended`: the device stopped publishing. `media_timeout`: no frames arrived for too long. `max_duration`: `maxDurationS` elapsed. `interrupted`: the analysis capacity was lost; create a new session. `policy`: the session broke the acceptable use policy. `error`: an internal failure.
          - **`inputs` (required)**: `object`, schema: `InputsPresence`

            Which inputs are arriving right now.
            - **`audio` (required)**: `object`
              - **`declared` (required)**: `boolean`

                You said the stream would carry the microphone.
              - **`present` (required)**: `boolean`

                Audio is arriving.
            - **`body` (required)**: `object`
              - **`declared` (required)**: `boolean`

                You said a body view would be published.
              - **`present` (required)**: `boolean`

                The body view is arriving.
            - **`face` (required)**: `object`
              - **`baselineReady` (required)**: `boolean`

                The person's resting baseline is in.
              - **`present` (required)**: `boolean`

                A face was tracked in the last second.
          - **`previousStatus` (required)**: `string | null`, possible values: `"starting", "ready", "calibrating", "analyzing", "ended", null`
          - **`status` (required)**: `string`, possible values: `"starting", "ready", "calibrating", "analyzing", "ended"`

            `starting`: analysis capacity is being prepared (a few minutes when none is warm). `ready`: the device can publish. `calibrating`: media is arriving and the person's baseline is being taken. `analyzing`: every signal the inputs allow is running. `ended`: no more events follow.
        - **`type` (required)**: `string`, const: `"session.status"`

      schema: `SessionStatusEvent`

      The live session changed status, or its inputs changed.
    - **All of:**, type: `input.warning`
      - *Schema `EventBase` is shown above.*
      - `object`
        - **`data` (required)**: `object`, schema: `InputWarningData`
          - **`code` (required)**: `string`, possible values: `"face_not_visible", "multiple_faces", "audio_absent", "baseline_pending", "body_stream_absent", "low_confidence"`

            `face_not_visible`: no face is tracked. `multiple_faces`: more than one face is in view and the analysis cannot tell which is the subject. `audio_absent`: the stream carries no microphone, so onset, peak and end are unavailable. `baseline_pending`: imminence starts once the baseline is in. `body_stream_absent`: a declared body view is not arriving. `low_confidence`: input quality is too low for confident calls.
          - **`message` (required)**: `string`

            A sentence you can show the person, in English.
          - **`sinceS` (required)**: `number`

            When the condition started, in stream seconds.
          - **`state` (required)**: `string`, possible values: `"raised", "cleared"`

            `raised` when the condition starts, `cleared` when it ends.
        - **`type` (required)**: `string`, const: `"input.warning"`

      schema: `InputWarningEvent`

      An input problem started (`raised`) or stopped (`cleared`). Show `message` to the person when it helps them fix it.
    - **All of:**, type: `recording.completed`
      - *Schema `EventBase` is shown above.*
      - `object`
        - **`data` (required)**: `object`, schema: `RecordingCompletedData`
          - **`durationS` (required)**: `number`

            Length of the recording, in seconds.
          - **`orgasmCount` (required)**: `integer`, minimum: `0`

            How many orgasms the analysis called in the recording.
          - **`subject` (required)**: `object`
            - **`pWoman` (required)**: `number | null`, minimum: `0`, maximum: `1`
            - **`sex` (required)**: `string`, possible values: `"woman", "man", "undetermined"`
        - **`type` (required)**: `string`, const: `"recording.completed"`

      schema: `RecordingCompletedEvent`

      A recording finished processing. Fetch its events with `listRecordingEvents`.
    - **All of:**, type: `recording.failed`
      - *Schema `EventBase` is shown above.*
      - `object`
        - **`data` (required)**: `object`, schema: `RecordingFailedData`

          *Schema `RecordingFailedData` is shown above.*
        - **`type` (required)**: `string`, const: `"recording.failed"`

      schema: `RecordingFailedEvent`

      A recording could not be processed.

    schema: `EventUnion`

    Any event. Switch on `type`.
- **`resultsExpireAt` (required)**: `string | null`, format: `date-time`
- **`retentionDays` (required)**: `integer`
- **`sandbox` (required)**: `object | null`, schema: `SandboxOptions`

  Test mode only. Refused with `sandbox_only` when sent with a live key.
  - **`scenario`**: `string`, possible values: `"woman-onset-end", "man-peak", "undetermined", "face-only", "face-lost", "edge", "ruin", "finish"`

    A deterministic sandbox scenario. `woman-onset-end`: a woman's orgasm, onset then end. `man-peak`: a man's peak, then the end read from his face. `undetermined`: the subject read stays undetermined, so every detector runs. `face-only`: no microphone, so imminence and the subject read only. `face-lost`: the face leaves the frame for 20 seconds, then returns. `edge`: imminence rises and falls three times without an orgasm. `ruin`: imminence crosses the point of no return and a peak follows. `finish`: a build-up, an onset and an end.
  - **`speed`**: `number`, minimum: `1`, maximum: `60`

    How many times faster than real time the scenario plays: 10 by default for live sessions, 60 for recordings. Stream times in events stay on the scenario's own clock.
- **`source` (required)**: `object`
  - **`type` (required)**: `string`, possible values: `"upload", "url"`
  - **`url`**: `string`

    The URL the enclave fetched, without its query string.
- **`startedAt` (required)**: `string | null`, format: `date-time`

  When processing started.
- **`status` (required)**: `string`, possible values: `"awaiting_upload", "queued", "processing", "completed", "failed"`

  Where a recording is in processing.
- **`subjectHint` (required)**: `string | null`, possible values: `"woman", "man", null`
- **`uploads` (required)**: `object | null`

  Where to upload, while `status` is `awaiting_upload`; `null` after.
  - **`body` (required)**: `object | null`, schema: `Upload`

    Where to `PUT` one video file.
    - **`expiresAt` (required)**: `string`, format: `date-time`
    - **`headers` (required)**: `object`

      Headers to send with the upload.

      **Additional properties:**

      `string`
    - **`maxBytes` (required)**: `integer`
    - **`method` (required)**: `string`, const: `"PUT"`
    - **`sealed` (required)**: `boolean`

      The body must be sealed to the enclave before upload, as the SDK does, so that only the enclave can read it. Always `false` in the sandbox.
    - **`url` (required)**: `string`, format: `uri`
  - **`face` (required)**: `object`, schema: `Upload`

    Where to `PUT` one video file.

    *Schema `Upload` is shown above.*
- **`userReference` (required)**: `string | null`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

  The `userReference` it was submitted with, or `null`.
- **`webhookEndpointId` (required)**: `string | null`

**Example: completed**

A sandbox recording after processing

Returned by getRecording after processing.

```json
{
  "id": "rec_2n5v8c1x4m7q0w3e6r9t",
  "object": "recording",
  "mode": "test",
  "status": "completed",
  "source": {
    "type": "upload"
  },
  "uploads": null,
  "inputs": {
    "audio": true,
    "body": false
  },
  "progress": null,
  "result": {
    "subject": {
      "sex": "man",
      "pWoman": 0.07,
      "secondsObserved": 30,
      "decidedAtS": 31,
      "hint": null,
      "detectors": [
        "peak",
        "face_end"
      ]
    },
    "summary": {
      "durationS": 780,
      "orgasmCount": 1,
      "orgasms": [
        {
          "orgasmIndex": 1,
          "detectors": [
            "peak",
            "face_end"
          ],
          "onsetAtS": null,
          "peakAtS": 701,
          "endAtS": 742,
          "durationS": 41,
          "confidence": "high"
        }
      ]
    },
    "timeline": [
      {
        "id": "evt_2aq0wyoeyck0k8yhwknk",
        "object": "event",
        "type": "subject.identified",
        "mode": "test",
        "recordingId": "rec_2n5v8c1x4m7q0w3e6r9t",
        "sequence": 1,
        "streamTimeS": 31,
        "confidence": "high",
        "data": {
          "sex": "man",
          "pWoman": 0.07,
          "secondsObserved": 30,
          "decidedAtS": 31,
          "hint": null,
          "detectors": [
            "peak",
            "face_end"
          ]
        },
        "wallTime": "2026-10-16T14:00:20.517Z"
      },
      {
        "id": "evt_1m1ugxow8zk03ybhqpq6",
        "object": "event",
        "type": "orgasm.peak",
        "mode": "test",
        "recordingId": "rec_2n5v8c1x4m7q0w3e6r9t",
        "sequence": 645,
        "streamTimeS": 704.2,
        "confidence": "high",
        "data": {
          "orgasmIndex": 1,
          "eventAtS": 701,
          "calledAtS": 704.2,
          "lagS": 3.2,
          "detector": "peak",
          "score": 0.66,
          "threshold": 0.5
        },
        "wallTime": "2026-10-16T14:00:31.737Z"
      },
      {
        "id": "evt_2ecvtv7npvg2760yypya",
        "object": "event",
        "type": "orgasm.end",
        "mode": "test",
        "recordingId": "rec_2n5v8c1x4m7q0w3e6r9t",
        "sequence": 687,
        "streamTimeS": 745.5,
        "confidence": "high",
        "data": {
          "orgasmIndex": 1,
          "eventAtS": 742,
          "startedAtS": 701,
          "durationS": 41,
          "calledAtS": 745.5,
          "lagS": 3.5,
          "detector": "face_end",
          "score": null,
          "threshold": null,
          "ruined": false
        },
        "wallTime": "2026-10-16T14:00:32.425Z"
      }
    ]
  },
  "failure": null,
  "subjectHint": null,
  "retentionDays": 30,
  "webhookEndpointId": null,
  "userReference": null,
  "clientReferenceId": null,
  "metadata": {},
  "sandbox": {
    "scenario": "man-peak",
    "speed": 60
  },
  "createdAt": "2026-10-16T14:00:00Z",
  "startedAt": "2026-10-16T14:00:20Z",
  "completedAt": "2026-10-16T14:13:20Z",
  "resultsExpireAt": "2026-11-15T14:13:20Z"
}
```

### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

schema: `Problem`

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

- **`code` (required)**: `string`, possible values: `"invalid_request", "consent_required", "capability_required", "sandbox_only", "authentication_required", "invalid_api_key", "live_mode_unavailable", "credits_exhausted", "permission_denied", "not_found", "idempotency_key_reused", "session_ended", "sandbox_no_media", "upload_already_received", "payload_too_large", "rate_limited", "capacity_unavailable", "internal_error"`

  A stable, machine-readable error code.
- **`status` (required)**: `integer`

  The HTTP status code.
- **`title` (required)**: `string`

  A short summary of the error.
- **`type` (required)**: `string`, format: `uri`

  A link to the docs for this error.
- **`detail`**: `string`

  What went wrong in this request, and what to do.
- **`errors`**: `array`

  Each contract violation, when the body or a parameter did not match the contract.

  **Items:**
  - **`location` (required)**: `string`, possible values: `"path", "query", "header", "cookie", "body"`
  - **`message` (required)**: `string`
  - **`path` (required)**: `string`

    JSON pointer to the value at fault.
- **`instance`**: `string`

  The request path.
- **`param`**: `string | null`

  The request field at fault, as a dotted path, when there is one.
- **`requestId`**: `string`

**Example:**

```json
{
  "type": "https://orgasm.dev/docs/guides/errors#invalid_api_key",
  "title": "The API key is not valid",
  "status": 401,
  "code": "invalid_api_key",
  "detail": "Send a secret key as `Authorization: Bearer sk_test_…`. In the sandbox any key that starts with sk_test_ works.",
  "requestId": "req_3k6m9q2t5w8z1c4f7h0j"
}
```

### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

*Schema `Problem` is shown above.*

**Example:**

```json
{
  "type": "https://orgasm.dev/docs/guides/errors#live_mode_unavailable",
  "title": "Live analysis is not available yet",
  "status": 403,
  "code": "live_mode_unavailable",
  "detail": "Live keys are not accepted yet. Use a key that starts with sk_test_ to reach the sandbox.",
  "requestId": "req_3k6m9q2t5w8z1c4f7h0j"
}
```

### 404 No such resource for this key's mode.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

*Schema `Problem` is shown above.*

**Example:**

```json
{
  "type": "https://orgasm.dev/docs/guides/errors#not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No live session ls_8f3kq2m7x9w4c1n6t5ra in test mode.",
  "requestId": "req_3k6m9q2t5w8z1c4f7h0j"
}
```

### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

*Schema `Problem` is shown above.*

**Example:**

```json
{
  "type": "https://orgasm.dev/docs/guides/errors#rate_limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited",
  "detail": "Retry after 2 seconds.",
  "requestId": "req_3k6m9q2t5w8z1c4f7h0j"
}
```

## Schemas

### EventType

**Type:** `string`, possible values: `"imminence.updated", "signals.updated", "stimulation.updated", "orgasm.onset", "orgasm.peak", "orgasm.end", "edge.completed", "subject.identified", "session.status", "input.warning", "recording.completed", "recording.failed"`

The kind of event. New types can be added at any time; ignore a type you do not recognise rather than failing.

### Confidence

**Type:** `string | null`, possible values: `"high", "medium", "low", null`

How complete the input behind this event was. `high`: the face was tracked throughout the window the signal reads and every input it uses was present. `medium`: an input was missing or partial for part of that window. `low`: the event rests on degraded input, or comes from a detector that ran while the subject was undetermined. `null` on events that are not signals (`session.status`, `input.warning`, `recording.*`). Confidence describes the input, not a calibrated probability that the event is right.

### Detector

**Type:** `string`, possible values: `"onset_end", "peak", "face_end"`

Which detector made a call. `onset_end` calls the start and the end of an orgasm and applies to women. `peak` calls a single peak and applies to men. `face_end` calls the end of a man's orgasm from the face alone.

- `EventBase` — shown above.
- `RecentCall` — shown above.
- `ImminenceData` — shown above.
- `OrgasmOnsetData` — shown above.
- `OrgasmPeakData` — shown above.
- `OrgasmEndData` — shown above.
- `EdgeCompletedData` — shown above.
- `SubjectIdentifiedData` — shown above.
- `InputsPresence` — shown above.
- `SessionStatusData` — shown above.
- `InputWarningData` — shown above.
- `FaceRegions` — shown above.
- `FaceExpression` — shown above.
- `HeadPose` — shown above.
- `FaceChannels` — shown above.
- `SignalsData` — shown above.
- `StimulationChannel` — shown above.
- `StimulationDevice` — shown above.
- `StimulationData` — shown above.
- `RecordingCompletedData` — shown above.
- `RecordingFailedData` — shown above.
- **imminence.updated** (`ImminenceUpdatedEvent`) — shown above.
- **signals.updated** (`SignalsUpdatedEvent`) — shown above.
- **stimulation.updated** (`StimulationUpdatedEvent`) — shown above.
- **orgasm.onset** (`OrgasmOnsetEvent`) — shown above.
- **orgasm.peak** (`OrgasmPeakEvent`) — shown above.
- **orgasm.end** (`OrgasmEndEvent`) — shown above.
- **edge.completed** (`EdgeCompletedEvent`) — shown above.
- **subject.identified** (`SubjectIdentifiedEvent`) — shown above.
- **session.status** (`SessionStatusEvent`) — shown above.
- **input.warning** (`InputWarningEvent`) — shown above.
- **recording.completed** (`RecordingCompletedEvent`) — shown above.
- **recording.failed** (`RecordingFailedEvent`) — shown above.
- `Problem` — shown above.

### ErrorCode

**Type:** `string`, possible values: `"invalid_request", "consent_required", "capability_required", "sandbox_only", "authentication_required", "invalid_api_key", "live_mode_unavailable", "credits_exhausted", "permission_denied", "not_found", "idempotency_key_reused", "session_ended", "sandbox_no_media", "upload_already_received", "payload_too_large", "rate_limited", "capacity_unavailable", "internal_error"`

A stable, machine-readable error code.

### ScenarioName

**Type:** `string`, possible values: `"woman-onset-end", "man-peak", "undetermined", "face-only", "face-lost", "edge", "ruin", "finish"`

A deterministic sandbox scenario. `woman-onset-end`: a woman's orgasm, onset then end. `man-peak`: a man's peak, then the end read from his face. `undetermined`: the subject read stays undetermined, so every detector runs. `face-only`: no microphone, so imminence and the subject read only. `face-lost`: the face leaves the frame for 20 seconds, then returns. `edge`: imminence rises and falls three times without an orgasm. `ruin`: imminence crosses the point of no return and a peak follows. `finish`: a build-up, an onset and an end.

- `SandboxOptions` — shown above.
- `Metadata` — shown above.

### UserReference

**Type:** `string`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

A pseudonymous id of your choosing for the person on camera, so that your company's costs can be broken down by person. Make it one orgasm.dev cannot trace to them, for example the hex HMAC-SHA256 of your user id under a key only you hold: never their email address, phone number, name or account name. At least one letter, and only letters, digits, `.`, `_`, `:` and `-`. It is erased when the session is purged, and 13 months after the session ends.

### ClientReferenceId

**Type:** `string`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

Your own id for the session, for example your session, order or round id, to join orgasm.dev's charges to your records. At least one letter, and only letters, digits, `.`, `_`, `:` and `-`. Erased with the session's `userReference`.

- `EventUnion` — shown above.

### RecordingStatus

**Type:** `string`, possible values: `"awaiting_upload", "queued", "processing", "completed", "failed"`

Where a recording is in processing.

- `Upload` — shown above.
- `OrgasmSummary` — shown above.
- `RecordingResult` — shown above.
- `Recording` — shown above.
