Tracearr History

Most Tracearr builders below use the Public API history endpoints and their pagination and filtering support. Kometa prefers /api/v2/public/history and automatically falls back to /api/v1/public/history when v2 is unavailable. tracearr_watched_media instead uses its purpose-built v2 endpoint when Tracearr advertises that capability.

Builder	Description
tracearr_popular	Gets items watched by the most unique Tracearr users.
tracearr_watched	Gets items with the most completed Tracearr sessions.
tracearr_watched_media	Gets Tracearr's distinct set of watched or partially watched items. Unlike tracearr_watched, this is not a chart ranked by completed sessions.
tracearr_trending	Gets the most active items from recent Tracearr watch history.
tracearr_rewatched	Gets items repeatedly played by the same Tracearr user.
tracearr_completed	Gets the most recently completed items from the Tracearr watch history feed.
tracearr_binged	Gets shows ranked by distinct completed episodes watched by a single Tracearr user.
tracearr_transcoded	Gets items ranked by Tracearr sessions that required audio or video transcoding.
tracearr_watch_time	Gets items ranked by total time watched.
tracearr_in_progress	Gets a user's most recently played unfinished movies and exact episodes. This builder is playlist-only and requires Tracearr v2 and user.
tracearr_history	Gets every movie/show in the Tracearr watch history feed.

Attribute	Description	Required	Default
list_days	Number of days to look back in the history.		30
list_minimum	Minimum activity required. This is unique users for popular; completed plays for watched/completed; repeat plays for rewatched; distinct completed episodes for binged; transcode plays for transcoded; total watched minutes for watch_time; and total plays for the other builders.		0
list_size	Number of Movies/Shows to add to this list.		10
user	Limits history to a Tracearr identity. Accepts the identity UUID, Tracearr username, Plex account ID, media-server user ID, or linked account username. Required by tracearr_in_progress.
watched	Filters plays by Tracearr's completed-watch state.
minimum_progress	Minimum play completion percentage from 0 through 100.		1 for in_progress
maximum_progress	Maximum play completion percentage from 0 through 100.		84 for in_progress
transcode	Filters plays by whether video or audio was transcoded.
video_decision	Filters video playback by directplay, copy, or transcode.
audio_decision	Filters audio playback by directplay, copy, or transcode.
transcode_reason	Case-insensitive text contained in one of Tracearr's transcode reasons.
subtitle_decision	Filters by the subtitle decision, such as burn.
platform	Filters by client platform.
device	Filters by playback device.
resolution	Filters by Tracearr's displayed source resolution, such as 4K.
source_video_codec	Filters by source video codec, such as hevc.
source_audio_codec	Filters by source audio codec, such as truehd.
genre	Filters by an exact, case-insensitive Tracearr genre.

The sync_mode: sync and collection_order: custom settings are recommended since the list is continuously updated.

Tracearr playlist builders can combine movie and show libraries from the same Plex server. A single playlist definition cannot combine Tracearr history from multiple Plex servers.

Kometa probes Tracearr's v2 Public API when connecting. When v2 is available, Kometa uses its history identity fields to match each play to its originating Plex library and exact Plex rating key. Movie playlists use the provider IDs supplied by Tracearr directly. Tracearr versions without v2 automatically use the v1 endpoint, and title/year matching is retained for older history records without library identity. Friendly cross-account user matching requires Tracearr v2; the other filters use whichever fields are available from the installed Tracearr version.

Identical history requests are reused during the same Kometa run, reducing repeated pagination and pressure on Tracearr's shared v2 API rate limit.

Tracearr Watched Media

tracearr_watched_media uses /api/v2/public/watched-media, when provided by the installed Tracearr version. The endpoint returns compact, distinct media records rather than every playback session, permits up to 1,000 records per page, and supplies provider IDs for direct matching. Kometa checks Tracearr's v2 API specification for this individual capability because early Public API v2 releases do not include it.

This builder is all-time by default. Set list_days to retain only records whose last_watched_day falls within that many days. Results remain ordered by most recent activity.

Attribute	Description	Required	Default
list_size	Maximum number of Movies, Shows, or Episodes to add.		10
list_days	Optionally limits results to media active within this many days.		All time
user	Limits watched state to one Tracearr identity. Accepts the same identity values as the history builders.		All users
min_state	Lowest state to include. watched returns completed media; partial includes both partially and completely watched media.		watched

Movie libraries are matched by TMDb or IMDb ID. Show libraries are matched by TVDb, TMDb, or IMDb ID. With builder_level: episode, episodes are matched by the parent show's TVDb ID plus season and episode numbers, with an episode IMDb ID as a fallback. Mixed-library playlists request movies and shows separately and merge them into one recent-first result.

collections:
  Watched by Anthony:
    sync_mode: sync
    collection_order: custom
    tracearr_watched_media:
      user: Anthony
      min_state: watched
      list_size: 100

collections:
  Recently Started:
    sync_mode: sync
    collection_order: custom
    tracearr_watched_media:
      user: Anthony
      min_state: partial
      list_days: 30
      list_size: 50

Tracearr History Builders

tracearr_binged requires at least two distinct completed episodes and works with Show libraries. In playlists, it returns shows only.

tracearr_in_progress requires Tracearr's v2 Public API. It examines the latest play for each movie or show so an older partial play is not returned after the user subsequently completed that item. Movies are matched by provider ID and shows add the exact unfinished episode using its Plex rating key. The builder is restricted to playlists to keep user-specific viewing activity out of shared Plex collections.

Tracearr Configuration

Configuring Tracearr in the config is required for this builder.

Example Tracearr History Builder(s)

collections:
  Tracearr History:
    sync_mode: sync
    collection_order: custom
    tracearr_history:
      list_days: 30
      list_size: 10

collections:
  Most Watched by Time:
    sync_mode: sync
    collection_order: custom
    tracearr_watch_time:
      list_days: 30
      list_minimum: 60
      list_size: 20
      platform: Apple TV

playlists:
  Continue Watching with Tracearr:
    sync_mode: sync
    collection_order: custom
    tracearr_in_progress:
      user: Anthony
      list_days: 30
      minimum_progress: 10
      maximum_progress: 84
      list_size: 20

collections:
  Tracearr Popular:
    sync_mode: sync
    collection_order: custom
    tracearr_popular:
      list_days: 30
      list_size: 10