Get an analytics report
const url = 'https://example.com/api/v1/analytics?period=example';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://example.com/api/v1/analytics?period=example' \ --header 'Authorization: Bearer <token>'Return activity and time metrics for a period and its comparison range. Choose day, week, month, quarter, or year with period; anchor defaults to today. Set both vs_from and vs_to to choose a custom comparison range. Otherwise, the server uses the previous range. Set tz and week_start to control local dates. Route: /api/v1/analytics. Inputs: period, anchor, vs_from, vs_to, tz, week_start. Safe reads can use bounded retries.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”day, week, month, quarter or year.
Any day inside the current period, YYYY-MM-DD. Defaults to today.
First day of the comparison range, YYYY-MM-DD. Give both vs_from
and vs_to, or neither for the previous range of the same unit.
Last day of the comparison range, YYYY-MM-DD, inclusive.
IANA time zone for “today” and for the day of each file. Defaults to UTC.
First day of the week, 0 = Sunday … 6 = Saturday. Defaults to 1. A 7-day window that starts on any day uses the anchor’s own weekday.
Responses
Section titled “Responses”Time tracked, activity counts and habits for a range and its comparison
The Analytics report.
object
A range and its metrics.
object
First day, YYYY-MM-DD.
Range metrics: the dashboard’s numbers (calternal.js RangeMetrics).
object
Days with at least one Log entry (moments count).
Items added in the range, per type.
object
Bookmarks and web clips saved.
Events on the day, from connected calendars.
Files added or changed (photos and Notes excluded).
Log entries (moments included).
Notes saved (bookmarks excluded).
Photos and videos in Photos/.
Tasks created.
Reversed ranges.
Days in the range, empty days included.
Timed Log entries.
Category minutes over the range, minutes DESC then key ASC. Can exceed the tracked total when entries overlap (“logged” vs “tracked”).
A category’s minutes. Fractional: an entry with several categories splits its time evenly.
object
Untracked waking minutes summed over active days.
Untracked waking minutes summed over every day.
Consecutive days with a Log entry, ending today (lookback about 60 days).
Sum over days of each day’s union of intervals.
Last day, YYYY-MM-DD, inclusive.
The comparison range has Log entries or items. When false, the UI shows “no comparison data” instead of a misleading +100%.
A range and its metrics.
object
First day, YYYY-MM-DD.
Range metrics: the dashboard’s numbers (calternal.js RangeMetrics).
object
Days with at least one Log entry (moments count).
Items added in the range, per type.
object
Bookmarks and web clips saved.
Events on the day, from connected calendars.
Files added or changed (photos and Notes excluded).
Log entries (moments included).
Notes saved (bookmarks excluded).
Photos and videos in Photos/.
Tasks created.
Reversed ranges.
Days in the range, empty days included.
Timed Log entries.
Category minutes over the range, minutes DESC then key ASC. Can exceed the tracked total when entries overlap (“logged” vs “tracked”).
A category’s minutes. Fractional: an entry with several categories splits its time evenly.
object
Untracked waking minutes summed over active days.
Untracked waking minutes summed over every day.
Consecutive days with a Log entry, ending today (lookback about 60 days).
Sum over days of each day’s union of intervals.
Last day, YYYY-MM-DD, inclusive.
One point per day of the current range.
One day of the current range, for the charts.
object
The day had a Log entry.
Items added on the day.
object
Bookmarks and web clips saved.
Events on the day, from connected calendars.
Files added or changed (photos and Notes excluded).
Log entries (moments included).
Notes saved (bookmarks excluded).
Photos and videos in Photos/.
Tasks created.
Category split, minutes DESC then key ASC.
A category’s minutes. Fractional: an entry with several categories splits its time evenly.
object
YYYY-MM-DD.
Sum of the category minutes (the stacked bars fill to this).
Union-tracked minutes (the calendar heat map).
Habits: streaks and the most active hours.
object
Streaks of the top categories of the current range (at most five).
A category’s streaks.
object
Consecutive days ending today with time in this category.
Days in the current range with time in this category.
The longest run of such days inside the current range.
Consecutive days with a Log entry, ending today.
Log entries per start hour over the current range, moments included.
Tracked minutes per hour of the day over the current range (24 values).
The longest run of active days inside the current range.
Up to three hours (0-23) with the most tracked time, most first. When no time is tracked, the hours with the most entries.
Active days per weekday over the current range (7 values, Monday first).
7 x 24 tracked minutes, weekday 0 = Monday, index weekday * 24 + hour.
The period kind.
Today in tz. Days before it are final; today is live.
The time zone used.
The waking day that untracked time is measured against, in minutes.
The first day of the week used.
Examplegenerated
{ "comparison": { "from": "example", "metrics": { "active_days": 1, "activity": { "bookmarks": 1, "events": 1, "files": 1, "log_entries": 1, "notes": 1, "photos": 1, "tasks": 1 }, "anomalies": 1, "calendar_days": 1, "event_count": 1, "logged_by_category": [ { "key": "example", "minutes": 1 } ], "missed_min_active": 1, "missed_min_all": 1, "streak_days": 1, "total_tracked_min": 1 }, "to": "example" }, "comparison_has_data": true, "current": { "from": "example", "metrics": { "active_days": 1, "activity": { "bookmarks": 1, "events": 1, "files": 1, "log_entries": 1, "notes": 1, "photos": 1, "tasks": 1 }, "anomalies": 1, "calendar_days": 1, "event_count": 1, "logged_by_category": [ { "key": "example", "minutes": 1 } ], "missed_min_active": 1, "missed_min_all": 1, "streak_days": 1, "total_tracked_min": 1 }, "to": "example" }, "days": [ { "active": true, "activity": { "bookmarks": 1, "events": 1, "files": 1, "log_entries": 1, "notes": 1, "photos": 1, "tasks": 1 }, "categories": [ { "key": "example", "minutes": 1 } ], "date": "example", "logged_min": 1, "tracked_min": 1 } ], "habits": { "categories": [ { "current_days": 1, "days": 1, "key": "example", "longest_days": 1 } ], "current_streak_days": 1, "hour_entries": [ 1 ], "hour_minutes": [ 1 ], "longest_streak_days": 1, "peak_hours": [ 1 ], "weekday_active_days": [ 1 ] }, "hour_matrix": [ 1 ], "period": "example", "today": "example", "tz": "example", "waking_min": 1, "week_start": 1}The standard API error response: { "error": { ... } }.
object
Example
{ "error": { "code": "bad_request" }}The standard API error response: { "error": { ... } }.
object
Example
{ "error": { "code": "bad_request" }}