Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ActivityWatch/activitywatch/llms.txt

Use this file to discover all available pages before exploring further.

ActivityWatch organizes all tracked data as events stored in buckets. Understanding this model is the foundation for working with the REST API, writing watchers, and building queries.

​
Events

An event represents a discrete period of activity. Every event has three fields:
FieldTypeDescription
idintegerAuto-assigned unique identifier
timestampISO 8601 stringWhen the event started (UTC)
durationfloat (seconds)How long the event lasted
dataobjectArbitrary key-value payload specific to the watcher type

​
Example events

Window watcher event: 
{
  "id": 1,
  "timestamp": "2024-01-15T09:30:00.000Z",
  "duration": 45.2,
  "data": {
    "app": "Firefox",
    "title": "ActivityWatch - GitHub"
  }
}
AFK watcher event: 
{
  "id": 2,
  "timestamp": "2024-01-15T09:30:00.000Z",
  "duration": 45.2,
  "data": {
    "status": "not-afk"
  }
}

​
Buckets

A bucket is a named container for events from a single watcher on a single host. Buckets group related events by their source.
FieldTypeDescription
idstringUnique identifier, e.g. aw-watcher-window_hostname
typestringEvent schema type, e.g. currentwindow
clientstringName of the watcher that created the bucket
hostnamestringMachine the bucket’s data came from
createdISO 8601 stringWhen the bucket was created

​
Naming convention

Bucket IDs follow the pattern {watcher-name}_{hostname}: 
aw-watcher-window_my-laptop
aw-watcher-afk_my-laptop
aw-watcher-web-chrome_my-laptop
You can find all your bucket IDs on the Buckets page of the dashboard at http://localhost:5600, or by calling GET /api/0/buckets/.

​
Event types

Different watchers produce different data schemas: 
{ "app": "string", "title": "string" }
  • app — application/process name
  • title — window title
{ "status": "not-afk" | "afk" }
  • status — "not-afk" when the user is active, "afk" when idle
{ "url": "string", "title": "string", "audible": boolean, "incognito": boolean }
  • url — full URL of the active tab
  • title — page title
  • audible — whether the tab is playing audio
  • incognito — whether the tab is in a private/incognito window

​
Heartbeat merging

Watchers send heartbeats at a regular interval. If a new heartbeat arrives within pulsetime seconds and has identical data, the server extends the current event’s duration rather than creating a new one. This keeps storage efficient without losing resolution. 
heartbeat 1: timestamp=T, data={app: "Firefox"}
heartbeat 2: timestamp=T+2, data={app: "Firefox"}, pulsetime=5  → extends event 1
heartbeat 3: timestamp=T+6, data={app: "VSCode"},  pulsetime=5  → creates new event

REST API Overview

Query and manipulate buckets and events via HTTP

Writing Watchers

Use aw-client to send events from your own watcher

Build docs developers (and LLMs) love

Get started for freeTalk to us