> 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/providers/synchronization/adapter-trakt.md).

# Adapter: Trakt

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

{% hint style="info" %}
Connect Trakt first. Use: [Trakt (Authentication provider)](/crosswatch/providers/authentication/auth-trackers/auth-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/provider-rate-limiting.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`)
  * **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.

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

```
GET https://wiki.crosswatch.app/crosswatch/providers/synchronization/adapter-trakt.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.