ReadingPeriodDto

One bucket of the time series.

Buckets with no reading are absent rather than zero: a client knows the window it asked for and can fill the gaps, and a quiet year would otherwise be mostly padding.

bucketstringrequired

ISO date of the bucket's start. Weeks start on Monday.

Example: 2026-06-01

duration objectrequired

Reading time split by how it was arrived at.

Deliberately two numbers rather than one. Time from the compatibility surfaces is reconstructed from the gaps between their writes: it undercounts and cannot see reading done from a downloaded book at all. Presenting a combined figure is fine; hiding that part of it is an estimate is not.

inferredMsinteger<int64>required

Milliseconds reconstructed server-side. An underestimate.

Example: 900000

measuredMsinteger<int64>required

Milliseconds reported by a client that measured its own reading.

Example: 5400000

totalMsinteger<int64>required

Convenience sum of the two, so clients do not each reimplement it.

Example: 6300000

pagesReadinteger<int64>required

Example: 120

sessionsinteger<int64>required

Example: 4

ReadingPeriodDto

{
  "bucket": "2026-06-01",
  "duration": {
    "inferredMs": 900000,
    "measuredMs": 5400000,
    "totalMs": 6300000
  },
  "pagesRead": 120,
  "sessions": 4
}