> 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/connections/trackers/trakt.md).

# Trakt

{% tabs %}
{% tab title="End users" %}
Connect Trakt to synchronize supported activity and configure real-time scrobbling.<br>

<figure><img src="https://565675962-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3rh5THg1PdhVsBt3GALo%2Fuploads%2FhthSo317kp09OC20Xtft%2Fimage.png?alt=media&amp;token=4a228628-81a8-4866-b04c-d3652d246e13" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}

#### No Trakt app or VIP account needed

CrossWatch connects with a PIN code. You do not need to create a Trakt API app, and it works with free Trakt accounts.
{% endhint %}

{% hint style="info" %}
Trakt is also used for scrobbling (Watcher/Webhooks) when configured.
{% endhint %}

### 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](https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/trakt.md) for matching rules and feature restrictions.

#### Connect Trakt (PIN Flow, recommended)

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.

![](https://565675962-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3rh5THg1PdhVsBt3GALo%2Fuploads%2FYiYvkatUderPaDmlzDqY%2Fimage.png?alt=media\&token=a7d5bf5f-fe86-42c3-877e-f60c6a16e730)

3. Enter the link code at <https://auth.trakt.tv/activate> and approve CrossWatch.
4. 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.

{% hint style="warning" %}
Creating a Trakt app requires a verified GitHub account, and Trakt limits app creation to VIP accounts.
{% endhint %}

1. Create a Trakt app:
   1. Open <https://developer.trakt.tv/apps>
   2. Create a new app.
   3. Set **App name**: `CrossWatch`.
   4. Set **Redirect URIs**: `urn:ietf:wg:oauth:2.0:oob`.
   5. Leave **Allowed origins** empty.
   6. 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](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/playlists.md) 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](https://wiki.crosswatch.app/crosswatch/advanced-and-api/rate-limiting-and-retries.md).
  {% endtab %}

{% tab title="Power users" %}

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

#### Related docs

* Sync module: [Trakt module](https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/trakt.md)
* Adapter: [Adapter: Trakt](https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/trakt.md)
  {% endtab %}
  {% endtabs %}


---

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