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.
aw-client is the official Python client library for ActivityWatch. It wraps the REST API and provides convenient methods for creating buckets, sending heartbeats, querying events, and more.
Installation
ActivityWatchClient
from aw_client import ActivityWatchClient
client = ActivityWatchClient(
client_name, # str: unique name for your watcher/client
testing=False, # bool: use test server on port 5666
host="localhost", # str: server host
port=5600, # int: server port
protocol="http", # str: "http" or "https"
)
Key properties
client.client_hostname — the current machine’s hostname (useful for constructing bucket IDs)client.server_address — full base URL of the connected server
Methods
create_bucket
client.create_bucket(bucket_id: str, event_type: str) -> None
get_buckets
client.get_buckets() -> dict[str, dict]
get_events
client.get_events(
bucket_id: str,
limit: int = -1,
start: datetime = None,
end: datetime = None,
) -> list[Event]
aw_core.models.Event objects.
insert_events
client.insert_events(bucket_id: str, events: list[Event]) -> list[Event]
heartbeat
client.heartbeat(
bucket_id: str,
event: dict, # {"timestamp": datetime, "duration": float, "data": dict}
pulsetime: float, # seconds within which identical heartbeats are merged
queued: bool = False,
) -> Event
queued=True, heartbeats are batched and sent together for efficiency — useful in high-frequency watchers.
query
client.query(query: list[str], timeperiods: list[tuple]) -> list[list[Event]]
timeperiods is a list of (start, end) datetime tuples.
delete_bucket
client.delete_bucket(bucket_id: str) -> None
Event model
from aw_core.models import Event
from datetime import datetime, timezone
event = Event(
timestamp=datetime.now(timezone.utc),
duration=30.0,
data={"app": "Firefox", "title": "ActivityWatch - GitHub"}
)
The Event class is defined in aw-core (aw_core.models). Both aw-client and aw-core must be installed.
