Adapter: Trakt

Trakt adapter notes for syncing watchlist/history/ratings, including ETag caching and batching.

Trakt adapter lets CrossWatch sync with Trakt. It supports watchlist, ratings, and history.

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

CrossWatch rate-limits Trakt calls to reduce 429 Too Many Requests.

Default: 3.33 GET/sec, 1 write/sec.

Tuning: Provider rate limiting

What it supports

• Direction: source or target in a pair (one-way or two-way)

• Features:

  • Watchlist

  • Ratings (1–10)

  • History (plays with watched_at)

  • Playlists (not supported)

• Indexing: present-state snapshot (reads “what exists now”)

• IDs: trakt, imdb, tmdb, tvdb, and sometimes slug

Watchlist behavior

• Read: /sync/watchlist

• Write: add/remove watchlist entries

Ratings behavior

• Read: ratings for movies/shows/seasons/episodes

• Write: upsert and remove ratings

Trakt ratings are integers 1–10. Anything else is rejected.

History behavior

• Read: movie and episode play history

• Write:

  • Add = scrobble with watched_at

  • Remove = remove plays (“unscrobble”)

Multiple plays are supported by sending multiple distinct watched_at timestamps.

History options (advanced)

Options under Pair → History → Advanced

Add collections to Trakt

• When syncing history to Trakt, also writes collection membership.

• You can enable this separately for Movies and Shows.

• Default: Movies enabled.

• This can increase write volume on large libraries.

Number Fallback

• If episode IDs are missing but you have show IDs + season/episode numbers, CrossWatch posts using the shows → seasons → episodes payload.

Settings and state (advanced)

Endpoints used

Watchlist:

• GET /sync/watchlist

• POST /sync/watchlist

• POST /sync/watchlist/remove

Ratings:

• GET /sync/ratings/{movies|shows|seasons|episodes}

• POST /sync/ratings

• POST /sync/ratings/remove

History:

• GET /sync/history/{movies|episodes}

• POST /sync/history

• POST /sync/history/remove

Local cache and unresolved files

Stored under /config/.cw_state/.

• Watchlist ETag/shadow: trakt_watchlist.shadow.json

• Watchlist unresolved: trakt_watchlist.unresolved.json

• Ratings index cache: trakt_ratings.index.json

• History unresolved: trakt_history.unresolved.json

Diagnostics

• Logs are prefixed with [TRAKT:watchlist], [TRAKT:ratings], [TRAKT:history].

• Requests use retries with exponential backoff.

• Trakt rate-limit headers (X-RateLimit-*) are honored.

• OAuth tokens are refreshed automatically when needed.