API reference

Screen time and app usage

Daily screen time, up time and per-app foreground time of Windows devices, per UTC day.

Import the whole API:OpenAPI 3.1 Postman collection

These endpoints show how a Windows device was used, one UTC day at a time: how long a user was signed in with the session unlocked (screen time), how long the device was on and awake (up time), and how long each app was in the foreground (app usage). The WeGuard agent measures them on the device. They need the usage:read scope. Keep the following points in mind when you use the numbers.

Foreground time, not active use. The agent records which window is in front. It has no idle detection, so a window left in front counts until another app, a lock, sign-out, sleep or shutdown takes over.

UTC days. Each entry covers one calendar day in UTC, from midnight to midnight. A local day in another time zone spans two UTC dates. For example, in UTC-08:00, work done at 17:00 local time falls on the next UTC date.

Sessions count on the day they start. An app session that runs past midnight counts in full on the day it started. Screen time and up time are split at midnight instead.

Windows only today. Devices on other platforms return 422 unsupported_platform.

About 60 days of history. Older days return no entries, so store the data you want to keep.

Collection depends on the policy. WeGuard stores usage only while the device’s policy has Screen Time turned on. Days without data are left out. While collection.enabled is false, a missing day was not collected. It reflects the current policy only, so with true a missing day most likely means that the device was not used, but it can also be a day when the policy did not collect usage, or a day the device has not uploaded yet. History starts at the device’s current enrollment and is not filtered by policy, so it survives a policy change.

Known measurement limits. Time in an app that runs with administrator rights is not counted. Switching between windows of the same app can drop the time before the switch. After a crash or hard power-off, screen time and up time can read 86400 for the days the device was off. Two users signed in at the same time count twice in screen time, up to the 86400 cap.

The screen time day object

Screen time and up time of one device on one UTC day.

AttributeDescription

object string: Always screen_time_day.
date date: The UTC calendar day, YYYY-MM-DD.
dayStart timestamp: Start of the day, midnight UTC, inclusive.
dayEnd timestamp: End of the day, the next midnight UTC, exclusive.
screenTimeSeconds integernullable: Seconds during which a user was signed in with the session unlocked, from sign-in or unlock until lock, sign-out, sleep or shutdown. Summed over the device’s user sessions and capped at 86400. This is session time, not display-on time or active input, so a kiosk that never locks counts the whole day. null when no session was reported for the day, for example when the device was on but nobody signed in.
upTimeSeconds integernullable: Seconds the device was powered on and not asleep, at most 86400. null when no up time was reported for the day.
complete boolean: false for today (UTC). Only sessions that have ended are counted, so today’s values grow during the day. A running session is added when it ends, or at midnight UTC, when the agent splits it. Earlier days are true, but a device that was offline can still upload them late.

Example

{
  "object": "screen_time_day",
  "date": "2026-10-06",
  "dayStart": "2026-10-06T00:00:00Z",
  "dayEnd": "2026-10-07T00:00:00Z",
  "screenTimeSeconds": 27315,
  "upTimeSeconds": 33960,
  "complete": true
}

The app usage day object

Foreground time of one app on one device, for the sessions that started on one UTC day.

AttributeDescription

object string: Always app_usage_day.
date date: The UTC calendar day the sessions started on, YYYY-MM-DD. A session that runs past midnight counts in full on the day it started.
app object: The app, as the device identifies it.
app.identifier string: The Windows process name without .exe, as the device reports it, for example chrome, WINWORD or explorer. Store apps report their own process, for example CalculatorApp, or ApplicationFrameHost when the agent could not resolve it. Microsoft Management Console (mmc.exe) is the exception: it is reported by its window title, for example Computer Management, Event Viewer or the name of a saved console. That title is free text and can include a file or computer name. The identifier does not match the identifier of installed apps, which names apps by package family name or product code.
foregroundSeconds integer: Seconds the app’s window was in the foreground, summed over the day’s sessions. This is foreground time, not active input: a window left in front counts until another app, a lock, sign-out, sleep or shutdown takes the foreground.
sessionCount integer: Foreground sessions. Each runs from the app gaining the foreground to losing it.
lastUsedAt timestampnullable: When the latest of the day’s sessions ended. Sessions are not split at midnight, so this can fall on the next day. null when the device reported no end time.
complete boolean: false for today (UTC), true once the UTC day has ended. As with screen time, a device that was offline can still upload a completed day late. Unlike screen time, a completed day can also grow on a device that stays online. A session is recorded only when it ends, and then counts in full on the day it started. An app still in the foreground at midnight therefore adds to that earlier, complete day when it loses the foreground. On a kiosk that never locks, that can be days later. To sync incrementally, re-read a trailing window, for example the last 7 days, not only the days that are not yet complete.

Example

{
  "object": "app_usage_day",
  "date": "2026-10-06",
  "app": {
    "identifier": "chrome"
  },
  "foregroundSeconds": 9842,
  "sessionCount": 57,
  "lastUsedAt": "2026-10-06T15:21:09Z",
  "complete": true
}

List a device’s daily screen time

GET/v1/devices/{deviceId}/screen-time

Requiresusage:read

Returns the screen time and up time of a Windows device, one entry per UTC day that has data, newest first. Days without data are left out. If you omit since and until, you get the last 7 days, today included. This list is not paginated: a range covers at most 31 days, so every entry comes back in one list object, with hasMore always false and nextCursor always null. See Date ranges.

Screen time and app usage are personal data about the people who use your devices. WeGuard never returns the Windows user name, and each day covers every user of the device. Grant usage:read only to integrations that need it, and check local consent and works council requirements before you collect or export this data.

Path parameters

ParameterDescription

deviceId stringrequired: Id of the device. Case-insensitive.

Query parameters

ParameterDescription

since dateoptionaldefault 6 days before until: First day of the range (inclusive), as a UTC calendar date in the form YYYY-MM-DD, for example 2026-10-01. Must not be after until. The range can cover at most 31 days, both ends included. See Date ranges.
until dateoptionaldefault today (UTC): Last day of the range (inclusive), as a UTC calendar date in the form YYYY-MM-DD. Must not be later than today in UTC.

Example request

curl "https://api-gw.weguard.ai/core/v1/devices/6523f1c2a7b9d4001234567a/screen-time?since=2026-10-05&until=2026-10-07" \
  -H "Authorization: Bearer $WEGUARD_API_KEY"

const response = await fetch("https://api-gw.weguard.ai/core/v1/devices/6523f1c2a7b9d4001234567a/screen-time?since=2026-10-05&until=2026-10-07", {
  headers: { Authorization: `Bearer ${process.env.WEGUARD_API_KEY}` },
});

const body = await response.json();
if (!response.ok) {
  throw new Error(`${body.code}: ${body.detail} (requestId ${body.requestId})`);
}
console.log(body);

import os
import requests

response = requests.get(
    "https://api-gw.weguard.ai/core/v1/devices/6523f1c2a7b9d4001234567a/screen-time",
    params={"since": "2026-10-05", "until": "2026-10-07"},
    headers={"Authorization": f"Bearer {os.environ['WEGUARD_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Response

A list object whose data holds screen time day objects, newest first, plus collection. An empty data means there is no data in the range. If collection.enabled is false, nothing was collected. If it is true, the device was most likely not used, but the policy may have been off on those days, or the device has not uploaded them yet.

Besides the members of every list object, this list object has:

AttributeDescription

collection object: Whether the device’s current policy collects usage. Days without data are left out of data. While enabled is false, a missing day means that nothing was collected, not that the device was unused. It describes the policy now, not on each listed day. A device picks up a policy change at its next sync.
collection.enabled boolean: true when the device’s policy has Screen Time turned on.

200 OK

{
  "object": "list",
  "data": [
    {
      "object": "screen_time_day",
      "date": "2026-10-07",
      "dayStart": "2026-10-07T00:00:00Z",
      "dayEnd": "2026-10-08T00:00:00Z",
      "screenTimeSeconds": 5640,
      "upTimeSeconds": 5820,
      "complete": false
    },
    {
      "object": "screen_time_day",
      "date": "2026-10-06",
      "dayStart": "2026-10-06T00:00:00Z",
      "dayEnd": "2026-10-07T00:00:00Z",
      "screenTimeSeconds": 27315,
      "upTimeSeconds": 33960,
      "complete": true
    },
    {
      "object": "screen_time_day",
      "date": "2026-10-05",
      "dayStart": "2026-10-05T00:00:00Z",
      "dayEnd": "2026-10-06T00:00:00Z",
      "screenTimeSeconds": 25480,
      "upTimeSeconds": 31205,
      "complete": true
    }
  ],
  "hasMore": false,
  "nextCursor": null,
  "collection": {
    "enabled": true
  }
}

Errors

404resource_not_found
No device with this id exists in your account.
400invalid_parameter
since or until is not a date in the form YYYY-MM-DD, since is after until, until is later than today (UTC), or the range covers more than 31 days; or a parameter was sent twice.
400unknown_parameter
The request includes another query parameter. This list is not paginated, so it rejects limit, cursor and includeTotal too.
403insufficient_scope
The key lacks usage:read.
422unsupported_platform
The device is not a Windows device. Screen time and app usage are available for Windows devices only.

List a device’s daily app usage

GET/v1/devices/{deviceId}/app-usage

Requiresusage:read

Returns the foreground time of each app on a Windows device, one entry per app and UTC day, as a paginated list. Entries are ordered by date, newest first, then by app.identifier, ignoring case. Days and apps without data are left out. If you omit since and until, you get the last 7 days, today included. See Date ranges.

Path parameters

ParameterDescription

deviceId stringrequired: Id of the device. Case-insensitive.

Query parameters

ParameterDescription

since dateoptionaldefault 6 days before until: First day of the range (inclusive), as a UTC calendar date in the form YYYY-MM-DD, for example 2026-10-01. Must not be after until. The range can cover at most 31 days, both ends included. See Date ranges.
until dateoptionaldefault today (UTC): Last day of the range (inclusive), as a UTC calendar date in the form YYYY-MM-DD. Must not be later than today in UTC. If you omit it, the first page fixes today’s date and every nextCursor carries it, so all pages cover the same days, even after midnight UTC.
apps stringoptionaldefault all apps: Only return these apps. Pass a comma-separated list of identifiers, for example chrome,WINWORD. Matching ignores the case of ASCII letters. At most 50 apps, each 1 to 256 characters long.
limit integeroptionaldefault 100: Maximum number of items to return, from 1 to 1000.
cursor stringoptional: The nextCursor from the previous page. Send it unchanged, together with the same filters. See Pagination.
includeTotal booleanoptionaldefault false: Set to true to also return totalCount. It runs an extra count, so request it only when you need it.

Example request

curl "https://api-gw.weguard.ai/core/v1/devices/6523f1c2a7b9d4001234567a/app-usage?since=2026-09-30&until=2026-10-06&limit=4" \
  -H "Authorization: Bearer $WEGUARD_API_KEY"

const response = await fetch("https://api-gw.weguard.ai/core/v1/devices/6523f1c2a7b9d4001234567a/app-usage?since=2026-09-30&until=2026-10-06&limit=4", {
  headers: { Authorization: `Bearer ${process.env.WEGUARD_API_KEY}` },
});

const body = await response.json();
if (!response.ok) {
  throw new Error(`${body.code}: ${body.detail} (requestId ${body.requestId})`);
}
console.log(body);

import os
import requests

response = requests.get(
    "https://api-gw.weguard.ai/core/v1/devices/6523f1c2a7b9d4001234567a/app-usage",
    params={"since": "2026-09-30", "until": "2026-10-06", "limit": 4},
    headers={"Authorization": f"Bearer {os.environ['WEGUARD_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Response

A list object whose data holds app usage day objects, plus collection. An empty list with hasMore: false means there is no data in the range. If collection.enabled is false, nothing was collected. If it is true, the device was most likely not used, but the policy may have been off on those days, or the device has not uploaded them yet.

Besides the members of every list object, this list object has:

AttributeDescription

collection object: Whether the device’s current policy collects usage. Days without data are left out of data. While enabled is false, a missing day means that nothing was collected, not that the device was unused. It describes the policy now, not on each listed day. A device picks up a policy change at its next sync.
collection.enabled boolean: true when the device’s policy has Screen Time turned on.

200 OK

{
  "object": "list",
  "data": [
    {
      "object": "app_usage_day",
      "date": "2026-10-06",
      "app": {
        "identifier": "chrome"
      },
      "foregroundSeconds": 9842,
      "sessionCount": 57,
      "lastUsedAt": "2026-10-06T15:21:09Z",
      "complete": true
    },
    {
      "object": "app_usage_day",
      "date": "2026-10-06",
      "app": {
        "identifier": "explorer"
      },
      "foregroundSeconds": 1263,
      "sessionCount": 41,
      "lastUsedAt": "2026-10-06T15:18:52Z",
      "complete": true
    },
    {
      "object": "app_usage_day",
      "date": "2026-10-06",
      "app": {
        "identifier": "ms-teams"
      },
      "foregroundSeconds": 6127,
      "sessionCount": 33,
      "lastUsedAt": "2026-10-06T14:02:15Z",
      "complete": true
    },
    {
      "object": "app_usage_day",
      "date": "2026-10-06",
      "app": {
        "identifier": "OUTLOOK"
      },
      "foregroundSeconds": 4410,
      "sessionCount": 29,
      "lastUsedAt": "2026-10-06T15:25:30Z",
      "complete": true
    }
  ],
  "hasMore": true,
  "nextCursor": "ZDE6MjAyNi0xMC0wNjpvdXRsb29r",
  "collection": {
    "enabled": true
  }
}

Errors

404resource_not_found
No device with this id exists in your account.
400invalid_parameter
since or until is not a date in the form YYYY-MM-DD, since is after until, until is later than today (UTC), or the range covers more than 31 days; apps has an empty item, an item longer than 256 characters or more than 50 apps; limit or includeTotal is invalid; or a parameter was sent twice.
400unknown_parameter
The request includes a query parameter this endpoint does not accept.
400invalid_cursor
The cursor is malformed, or was issued for a different listing: another device, other apps, or another since / until.
403insufficient_scope
The key lacks usage:read.
422unsupported_platform
The device is not a Windows device. Screen time and app usage are available for Windows devices only.

Common errors

Besides the errors listed for each endpoint, any request can fail authentication, exceed the rate limit, ask for a format other than JSON, or fail with a server error. See Errors for the response format and retry guidance.

401missing_credentials
The request has no Authorization header.
401invalid_authorization_header
The Authorization header does not use the Bearer scheme, or has no key after it. The WWW-Authenticate header carries error="invalid_request".
401invalid_api_key
The key is malformed, does not exist, or its secret does not match. The WWW-Authenticate header carries error="invalid_token".
401api_key_expired
The key is past its expiresAt.
401api_key_revoked
An account admin revoked the key. Revocation takes effect immediately and cannot be undone.
403account_inactive
The WeGuard account that owns the key has been deleted or disabled.
406not_acceptable
The Accept header excludes JSON.
429rate_limit_exceeded
The key has used up its request budget. See Rate limits.
500internal_error
An unexpected error occurred on our side.
503service_unavailable
A service WeGuard depends on is temporarily unavailable, or reading the data took longer than the time WeGuard allows for it. This can also happen while your key is being checked, so it can be returned before authentication completes. The response carries Retry-After.

The screen time day object

The app usage day object

List a device’s daily screen time

Path parameters

Query parameters

Example request

Response

Errors

List a device’s daily app usage

Path parameters

Query parameters

Example request

Response

Errors

Common errors

We use cookies