> 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 lets CrossWatch sync with Trakt. It supports watchlist, ratings, history, and progress.

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

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

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

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

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

{% 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" %}
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.
{% endhint %}

### History options (advanced)

<details>

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

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

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


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.