Submit completed screentime usage segments for a session
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.
Authorization
api-key In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
curl -X POST "https://example.com/screentime/push" \ -H "Content-Type: application/json" \ -d '{ "sessionId": "b1a6482d-5242-4b4a-aa88-3fa52595a672", "events": [ { "id": "9d4e2f81-7a3b-4c56-8e90-1f2a3b4c5d6e", "durationSeconds": 1800, "timestamp": "2026-06-24T09:00:00Z" }, { "id": "c1b2a3d4-5e6f-4708-9a1b-2c3d4e5f6071", "durationSeconds": 2400, "timestamp": "2026-06-24T13:00:00Z" } ] }'{ "sessionId": "b1a6482d-5242-4b4a-aa88-3fa52595a672", "accepted": 2, "rejected": 0, "events": [ { "id": "9d4e2f81-7a3b-4c56-8e90-1f2a3b4c5d6e", "status": "accepted" }, { "id": "c1b2a3d4-5e6f-4708-9a1b-2c3d4e5f6071", "status": "accepted" } ]}{ "error": "INVALID_INPUT", "errorMessage": "The request was missing a sessionId parameter."}Get screentime state GET
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.
Request a screentime override POST
Submits an override request on the kid's behalf when they want more time today or to bypass active quiet hours. k-ID records the request and notifies the parent to approve or deny. Idempotent per kid: a call made while another request from the same kid is still pending returns that pending request unchanged rather than creating a second one. The resolution arrives asynchronously as a single `Screentime.OverrideResult` webhook with `status: "granted" | "denied" | "expired"`. The webhook body carries the same shape as `GET /screentime/get-state` under `state`, so the platform can update its copy of the state directly without a follow-up fetch. Requests that aren't resolved within 24 hours fire the webhook with `status: "expired"`.