Adapter: Tautulli

Tautulli adapter notes for importing Plex watch history into CrossWatch.

Tautulli adapter is a read-only history importer. It pulls old Plex plays from an existing Tautulli database and normalizes them.

Tautulli is not a tracker and not a media server. Don’t use it to “sync” back into Plex/Trakt/SIMKL/etc.

Connect Tautulli first. Use: Tautulli (Authentication provider).

What it supports

• Direction: source-only

• Features:

  • History (movies + episodes)

  • Watchlist / ratings / playlists (not supported)

• Writes: not supported (always read-only)

How indexing works

1. Pull pages from get_history until the end or a safety stop.

2. Keep only media_type in {movie, episode}.

3. Extract IDs from GUIDs + Plex/Tautulli keys (rating_key, grandparent_rating_key).

4. If IDs are incomplete, call get_metadata(rating_key) to enrich external IDs.

5. Emit normalized items keyed by external IDs where possible.

History is indexed as a de-duplicated snapshot. Newest entry wins per canonical key.

Output shape

Movie example

{
  "type": "movie",
  "ids": {
    "imdb": "tt123",
    "tmdb": "456",
    "tvdb": "0",
    "plex": "12345",
    "guid": "plex://movie/..."
  },
  "title": "…",
  "year": 2024,
  "watched_at": "2025-12-30T23:54:11Z"
}

Episode example

{
  "type": "episode",
  "ids": {
    "imdb": "ttSHOW",
    "tmdb": "157741",
    "tvdb": "397424",
    "plex": "40759",
    "guid": "plex://show/..."
  },
  "title": "Episode title",
  "year": 2025,
  "season": 2,
  "episode": 4,
  "watched_at": "2025-12-30T23:54:11Z",
  "series_title": "Show title (when available)",
  "show_ids": {
    "imdb": "ttSHOW",
    "tmdb": "157741",
    "tvdb": "397424",
    "plex": "40759",
    "guid": "plex://show/..."
  }
}

Workflows (recommended)

1

Import into CrossWatch (recommended)

Run a pair: Tautulli → CrossWatch with History enabled.

Then use CrossWatch (CW) as the source to seed Trakt/SIMKL/etc.

Related: Adapter: CrossWatch.

2

Import into Editor dataset

Use this if you want to clean history before syncing it anywhere:

• fix wrong matches

• remove junk plays

• merge duplicates

• correct titles/years

Endpoints used (for debugging)

API calls

• History pages: GET /api/v2?cmd=get_history

• Metadata enrichment (optional): GET /api/v2?cmd=get_metadata&rating_key=...