For the complete documentation index, see llms.txt. This page is also available as Markdown.

Trakt

Connect Trakt to synchronize supported activity and configure real-time scrobbling.

No Trakt app or VIP account needed

Trakt is also used for scrobbling (Watcher/Webhooks) when configured.

What CrossWatch can sync

Read brings data into CrossWatch; Write sends changes to this provider.

Feature
Read
Write
Notes

Watchlist

Yes

Yes

Movies and shows.

History

Yes

Yes

Movies and episodes.

Ratings

Yes

Yes

Movies, shows, seasons and episodes.

Progress

Yes

Yes

Resume positions for movies and episodes.

Playlists

Yes

Yes

Writable lists only; actions depend on ownership and permissions.

Collection

Yes

Yes

Movies, shows, seasons and episodes, with optional media info.

Live scrobbling: Scrobble destination; cannot be a Watcher source.

See the synchronization guide for matching rules and feature restrictions.

  1. Open the Trakt connection in CrossWatch. PIN Flow is selected by default.

  2. Click Connect Trakt. CrossWatch shows a link code and opens a new tab.

  1. Enter the link code at https://auth.trakt.tv/activate and approve CrossWatch.

  2. Return to CrossWatch. The status changes to Connected.

The link code is valid for 10 minutes. If it expires, click Restart to get a new one.

Connect with your own Trakt app (optional)

Use this only if you want CrossWatch to run on your own Trakt API app. Existing connections that were set up this way keep working and do not need to be changed.

  1. Create a Trakt app:

    1. Create a new app.

    2. Set App name: CrossWatch.

    3. Set Redirect URIs: urn:ietf:wg:oauth:2.0:oob.

    4. Leave Allowed origins empty.

    5. Save the app.

  2. In CrossWatch, select the Own app (Client ID) tab.

  3. Copy the Client ID and Client Secret into CrossWatch.

  4. Click Connect Trakt, then enter the link code at https://auth.trakt.tv/activate.

Switching methods

  • Each profile has its own method. One profile can use PIN Flow while another uses its own app.

  • To switch a connected profile, click Delete first, pick the other tab, and connect again.

  • Connecting with PIN Flow replaces the Client ID stored for that profile and clears its Client Secret.

Staying connected

  • CrossWatch refreshes your Trakt login automatically in the background. You do not need to reconnect every week.

  • If Trakt no longer accepts the login, CrossWatch shows Trakt login expired - reconnect. Click Connect Trakt again to fix it.

  • Logins created before Trakt changed its authentication can no longer be refreshed and need one reconnect.

Playlists

CrossWatch discovers the supported liked, followed, shared, and smart-list categories for the connected account. Ownership and collaboration determine whether a list is writable.

Liking or following a list does not grant edit access. Supported public lists can also be resolved by link.

See Playlists for playlist setup.

Troubleshooting

  • If the auth tab doesn't open, disable popup blockers for CrossWatch, or open https://auth.trakt.tv/activate yourself and enter the code.

  • If the code fails or has expired, click Restart to generate a new link code.

  • If you see Trakt login expired - reconnect, connect again. Your sync settings are kept.

  • CrossWatch paces Trakt requests automatically to stay within Trakt's limits. During a large sync it may pause for a few minutes and then continue.

  • If you still see 429 Too Many Requests, see the guide: Provider rate limiting.

Power users

Config keys

Stored under: trakt.*

Common keys:

  • trakt.auth_method: pin (built-in CrossWatch client) or app (your own Trakt app)

  • trakt.client_id: set automatically for PIN Flow, your own value for app

  • trakt.client_secret: only used for app

  • trakt.access_token, trakt.refresh_token, trakt.expires_at

  • trakt.auth_error: reconnect_required when Trakt rejected the login

  • trakt.rate_limit.get_per_sec, trakt.rate_limit.post_per_sec: sync pacing

Profiles other than the default store the same keys under trakt.instances.<profile>.*.

Tokens

  • Access tokens are valid for 7 days. Refresh tokens are single use and are replaced on every refresh.

  • A background worker checks hourly and refreshes a token when it is within 24 hours of expiring.

  • The PIN Flow never sends a client secret.

Rate limiting

All Trakt calls share one pacer per account:

  • Writes: 1 per second

  • Reads: 500 per 5 minutes

  • After a 429, calls for that account wait until Retry-After has passed

Environment variables

  • CROSSWATCH_TRAKT_CLIENT_ID: use a different client ID for PIN Flow

  • CW_TRAKT_READ_LIMIT: reads allowed per 5 minutes (default 500)

  • CW_TRAKT_PACING: set to 0 to turn the shared pacer off

  • CW_TRAKT_UA: custom User-Agent for Trakt calls

Last updated

Was this helpful?