Trakt

Trakt adapter notes for syncing watchlist, history, ratings, and progress.

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

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)
  • Progress
  • 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.

Trakt is currently the only provider with full multiple-play support.

CrossWatch does not preserve full multi-play history across providers.

Repeated plays can collapse to one history entry on providers without matching support.

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.