Get screentime state
Returns the current screentime state for a `sessionId`: the parent-set rules, today's usage, and whether the platform may permit play right now. Platforms call this at the start of a session and after `Screentime.LimitWarning`, `Screentime.LimitReached`, `Screentime.QuietHoursWarning`, or `Screentime.QuietHoursReached` webhooks to refresh their copy of the state. Returns `{ "enabled": false }` when the parent has not configured screentime for the session, or has configured it but disabled enforcement.
Authorization
api-key In: header
Query Parameters
uuidResponse Body
application/json
application/json
curl -X GET "https://example.com/screentime/get-state?sessionId=497f6eca-6276-4993-bfeb-53cbbbba6f08"{ "enabled": true, "access": { "allowed": true }, "state": { "timeUsedTodayMinutes": 75, "continuousUsageMinutes": 30, "timeLimitTodayMinutes": 120, "timeRemainingTodayMinutes": 45, "dayResetsAt": "2026-06-25T00:00:00Z" }, "schedule": { "timezone": "UTC", "breakReminderIntervalMinutes": 45, "dailyLimits": [ { "day": "mon", "limitMinutes": 120 }, { "day": "tue", "limitMinutes": 120 }, { "day": "wed", "limitMinutes": 120 }, { "day": "thu", "limitMinutes": 120 }, { "day": "fri", "limitMinutes": 120 }, { "day": "sat", "limitMinutes": 180 }, { "day": "sun", "limitMinutes": 180 } ], "quietHours": [ { "name": "Bedtime", "days": [ "mon", "tue", "wed", "thu", "fri" ], "start": "21:00", "end": "07:00" } ] }}{ "error": "INVALID_INPUT", "errorMessage": "The request was missing a sessionId parameter."}End screentime POST
Ends active screentime previously started with `/screentime/start`. The duration is counted toward today's screentime usage, split across day boundaries in the schedule's timezone when the screentime crosses local midnight. Status semantics: * `accepted` - the screentime matching `id` was ended, or a retried call for a screentime that was already ended was absorbed idempotently. A `NOT_FOUND` code is returned when no screentime is active for `sessionId`, or when the `id` in this request doesn't match the `id` that started the active screentime.
Submit completed screentime usage segments for a session POST
Submit one or more completed segments of screentime usage for a k-ID session. Each event records when a span of usage began and how long it lasted. Use this endpoint when usage is known only after the fact - for example, a backend that buffers segments and uploads them periodically, or a game engine that reports session totals on shutdown. Each accepted segment adds its `durationSeconds` to the player's daily screentime total. If a segment crosses midnight in the parent's configured timezone, it is split across both dates so each day's total reflects the usage that actually happened on that date. Events are processed independently. The response carries a per-event status: * `accepted` - the segment was recorded and added to the daily total. Resubmitting an event whose `id` was already accepted is a safe no-op: it counts as `accepted` again and is not added twice, so retries after a network failure won't double-count. * `rejected` - the segment failed validation; the `reason` identifies which rule. The whole batch is rejected when the session does not exist or is revoked. Real-time enforcement signals (`Screentime.LimitWarning`, `Screentime.LimitReached`, `Screentime.BreakReminder`) are not fired from this endpoint. Use `/screentime/start` + `/screentime/end` for integrations that need those webhooks to fire at the moment a threshold is crossed.