Timeline

The timeline is generated from GPS points and consists of stays (time spent at one place), trips (movement between stays, with a detected movement type), and data gaps (periods without GPS data). Use these endpoints to read the timeline for a time range, regenerate it after changing settings, and compare it with friends' timelines. All timestamps are ISO-8601 instants in UTC.

📄️ Get the timeline

Returns the stays, trips, and data gaps that overlap a time range, in chronological order. Items that start before `from` or end after `to` are included. Large ranges can return many items; check the size first with `GET /api/v1/timeline/count`.

📄️ Count timeline items

Returns the number of stays, trips, and data gaps in a time range, and the maximum number of items the web app shows at once. Use it to decide whether a range is small enough to load.

📄️ Regenerate the timeline

Starts a background job that rebuilds the whole timeline of the signed-in user from GPS points, using the current timeline settings. Manual overrides are kept. Only one timeline job per user can run at a time. Poll `GET /api/v1/timeline/jobs/{jobId}` for progress.

📄️ Get the running timeline job

Returns the timeline job that is currently running for the signed-in user, or `204 No Content` when none is running.

📄️ List recent timeline jobs

Returns recently finished timeline jobs of the signed-in user.

📄️ Get timeline job progress

Returns the progress of a timeline generation job: status, current step, and percentage.

📄️ Get timelines of several users

Returns the timelines of the signed-in user and of friends who share their timeline, for the same time range, so they can be compared. Without `userIds`, includes the signed-in user and every friend who granted timeline access.

📄️ Get effective timeline settings

Returns the timeline detection settings in effect for the signed-in user: the user's own preferences merged with the server defaults. Change them with `PUT /api/v1/preferences/timeline`.