> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/trakt.md).

# 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.

{% hint style="info" %}
Connect Trakt first. Use: [Trakt (Authentication provider)](https://wiki.crosswatch.app/crosswatch/settings/connections/trackers/trakt.md).
{% endhint %}

{% hint style="info" %}
CrossWatch rate-limits Trakt calls to reduce `429 Too Many Requests`.

Default: `1.66` GET/sec, `1` write/sec.

Tuning: [Provider rate limiting](https://wiki.crosswatch.app/crosswatch/advanced-and-api/rate-limiting-and-retries.md)
{% endhint %}

### What CrossWatch can sync

| 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.    |

**Read** brings data into CrossWatch; **Write** sends changes to this provider. Enable only features supported by both sides. Collection pairs are one-way only.

Connect the provider first: [Trakt setup](https://wiki.crosswatch.app/crosswatch/settings/connections/trackers/trakt.md).

### Watchlist behavior

* Read: `/sync/watchlist`
* Write: add/remove watchlist entries

### Playlist behavior

When creating a list in Playlists, choose **Private** (default), **Anyone with the link**, **Friends** or **Public**. Eligible owned lists can also change privacy later. See [List privacy](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/playlists.md#list-privacy).

The picker discovers supported liked, followed, shared, and smart-list categories. A discovered list is not necessarily writable.

Ownership and collaboration determine available actions. Liking or following a list does not grant edit permission. Supported public lists can be resolved by link.

Trakt smart lists remain subject to their provider restrictions. Confirm the available list actions before using them as a destination.

See [Playlists](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/playlists.md) for setup and list-link guidance.

### Collection behavior

Trakt can be a Collection source or target. Collection sync is one-way only.

The first run creates a baseline. Later runs process changes since that baseline.

### Ratings behavior

* Read: ratings for movies/shows/seasons/episodes
* Write: upsert and remove ratings

{% hint style="warning" %}
Trakt ratings are **integers 1–10**. Anything else is rejected.
{% endhint %}

### 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.

{% hint style="info" %}
Enable **Rewatches** on the sync pair to preserve separate plays when both sides support the required history capabilities. See [Rewatches](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/features/history/rewatches.md).

Repeated plays can collapse to one history entry on providers without matching support.
{% endhint %}

### Follow show rewatch resets

With Trakt VIP, a pair to Plex, Jellyfin, Emby, Kodi or Tofa can follow a show’s rewatch reset. Enable **Follow Trakt rewatch resets** under the pair’s **History** settings. It also works in two-way pairs, keeps Trakt history intact, and is off by default. See [Trakt rewatch resets](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/features/history/rewatches.md#follow-trakt-rewatch-resets) for the unwatch behavior and restrictions.

### History options (advanced)

<details>

<summary>Options under Pair → History</summary>

**Add to library**

* When syncing history **to Trakt**, also writes collection membership.
* You can enable this separately for **Movies** and **Shows**.
* **Add to library** is off by default. When enabled without a previous type selection, **Movies** is selected.
* This can increase write volume on large libraries.

</details>

### Settings and state (advanced)

<details>

<summary>Endpoints used</summary>

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`

</details>

<details>

<summary>Local cache and unresolved files</summary>

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`

</details>

### 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.

### Custom status mapping

For per-pair status rules, enable History and **Status mapping**, then configure **Providers → Status mapping**. See [Status mapping](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/provider-settings/status-mapping.md) for supported movie/show destinations, defaults, and restrictions. Planned stays managed by Watchlist.

### Unknown watch dates

Normal History sync can read and write watched states whose dates are unknown. With **Rewatches** enabled, undated watches are skipped while supported dated plays can still sync. See [Unknown watch dates](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/features/history.md#unknown-watch-dates) for destination support and the optional SIMKL date-conversion setting.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/trakt.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
