Screentime.LimitReached

Emitted when a player's usage meets or exceeds today's screentime limit. Paired with Screentime.LimitWarning, which fires earlier so the player is told before the limit lands rather than at it.

Subscribe your endpoint to this event

k-ID delivers Screentime.LimitReached only to endpoints subscribed to it, and drops it for the rest without a delivery attempt or an error. Select it for your endpoint on the product's Developer Settings page. See Before you start.

k-ID doesn't end the session, sign the player out, or block anything. It reports that the limit applies. What that means in your product is yours to decide, and GET /screentime/get-state is the endpoint to consult: when access.allowed is false and access.details.reason is limit_reached, access.details.resumesAt tells you when the restriction lifts.

Offer the player /screentime/request-override at this point so they can ask a parent for more time instead of being stuck. The parent's answer arrives as Screentime.OverrideResult.

Not fired by /screentime/push

As with the other real-time signals, this event is scheduled on /screentime/start and canceled on /screentime/end. /screentime/push counts usage but fires no enforcement events.

Fields

Field	Type	Required	Description
eventType	string	yes	Always "Screentime.LimitReached"
data	object	yes	Limit reached data
data.sessionId	string (UUID)	yes	Session ID the limit applies to
data.productId	number	yes	Product ID
data.timeUsedSeconds	number	yes	Today's usage in seconds, including the time in the session currently in flight
data.timeLimitSeconds	number	yes	Today's daily limit in seconds

timeUsedSeconds can exceed timeLimitSeconds slightly, because the value is measured when the event fires.

Example

{
  "eventType": "Screentime.LimitReached",
  "data": {
    "sessionId": "b1a6482d-5242-4b4a-aa88-3fa52595a672",
    "productId": 42,
    "timeUsedSeconds": 7200,
    "timeLimitSeconds": 7200
  }
}

When it doesn't fire

• The parent has no screentime schedule, or the schedule is disabled.
• No daily limit is set for today's weekday in the schedule's time zone.
• The limit was already reached earlier today.