Skip to main content

RecordReadingSessionsRequest

A batch of sessions to record.

sessions object[]required

The sessions to record. Order within the batch does not matter.

  • Array [
    • activeDurationMsinteger,null<int64>nullable

    Active reading time in milliseconds, measured by the reader.

    Must be time the reader actually spent reading, with the timer paused while the app is backgrounded, the screen is locked, or the reader has been idle past the timeout. Wall-clock elapsed is not this value, and anything larger than the session's own span is clamped to it.

    Example: 934000
    bookIdstring<uuid>required

    The book this session belongs to.

    Example: 550e8400-e29b-41d4-a716-446655440002
    clientEndedAtstring<date-time>required

    When this session ended, by the client's clock.

    This is what orders sessions against each other, so it must reflect when the reading happened rather than when it is being submitted. A session read offline and synced hours later still sorts by when it was read.

    Example: 2026-08-14T19:20:45Z
    clientStartedAtstring<date-time>required

    When this session began, by the client's clock.

    Example: 2026-08-14T19:02:11Z
    deviceIdstringrequired

    Stable identifier for the device that produced this session.

    Example: 8f3d1c7a-2b44-4e51-9c2a-1f7d3e5b9a01
    deviceNamestring | nullnullable

    Human-readable device name, for the reading statistics UI.

    Example: Ash's iPhone
    idstring<uuid>required

    Client-generated identifier for this session.

    Submitting the same id twice is a no-op, so a batch whose response was lost can be replayed without double-counting the reading.

    Example: 550e8400-e29b-41d4-a716-446655440000
    kindReadingSessionKindDto (string)required

    What this session asserts.

    Possible values: [progress, completed, reset]

    pagesReadinteger,null<int32>nullable

    Distinct pages advanced through during this session.

    Example: 31
    r2Progressionstring | nullnullable

    R2Progression JSON (Readium standard) for EPUB position sync.

    toPageinteger,null<int32>nullable

    Page reached, for comics and PDF (1-indexed).

    Example: 42
    toPercentagenumber,null<double>nullable

    Fraction read, for EPUB (0.0 to 1.0).

    Example: 0.45
  • ]
    • RecordReadingSessionsRequest
    {
      "sessions": [
        {
          "activeDurationMs": 934000,
          "bookId": "550e8400-e29b-41d4-a716-446655440002",
          "clientEndedAt": "2026-08-14T19:20:45Z",
          "clientStartedAt": "2026-08-14T19:02:11Z",
          "deviceId": "8f3d1c7a-2b44-4e51-9c2a-1f7d3e5b9a01",
          "deviceName": "Ash's iPhone",
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "kind": "progress",
          "pagesRead": 31,
          "r2Progression": "string",
          "toPage": 42,
          "toPercentage": 0.45
        }
      ]
    }