> 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/media-servers/plex.md).

# Plex

Plex adapter notes for syncing watchlist/history/ratings with stable external IDs.

Plex adapter lets CrossWatch (CW) sync with Plex. It supports watchlist, history, ratings, and progress. It prefers stable external IDs.

{% hint style="info" %}
Connect Plex first. Use: [Plex (Authentication provider)](/crosswatch/settings/connections/media-servers/plex.md).
{% endhint %}

### What CrossWatch can sync

| Feature    | Read | Write | Notes                                                                                                                                        |
| ---------- | ---- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Watchlist  | Yes  | Yes   | Movies and shows in the authenticated Plex account.                                                                                          |
| History    | Yes  | Yes   | Library movies and episodes; reads retained plays, writes watched state.                                                                     |
| Ratings    | Yes  | Yes   | Movies, shows, seasons and episodes. Shared-server tokens cannot sync personal ratings.                                                      |
| Progress   | Yes  | Yes   | Resume positions for library movies and episodes.                                                                                            |
| Playlists  | Yes  | Yes   | Server playlists, manual collections and owned cloud Lists; smart resources are read-only. Cloud Lists need the selected user’s own account. |
| Collection | Yes  | No    | Selected library inventory; source only. Does not add or delete media files.                                                                 |

**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: [Plex setup](/crosswatch/settings/connections/media-servers/plex.md).

### Playlists and cloud Lists

Use [Playlists](/crosswatch/main-dashboard/navigation/playlists.md#plex) to select a server playlist, server collection or **Cloud list**. Cloud Lists can include titles outside your server and work with an account connection without a server. Connect the selected user's own Plex account; managed Home users and server-scoped shared tokens cannot access them.

Owned cloud Lists support creation, rename, deletion, membership changes, ordering and [privacy changes](/crosswatch/main-dashboard/navigation/playlists.md#list-privacy). They default to **Private**. Movies, shows, seasons and episodes must match Plex's online catalog by ID; missing or ambiguous matches remain unresolved.

Manual server collections support rename, deletion and membership changes, but not ordering. Create them in Plex first. Smart playlists and collections remain read-only sources. If cloud Lists are missing, check the selected account and refresh the list picker; server-list access alone does not grant cloud-list access.

### How matching works

CW tries to match by provider IDs first.

* Watchlist: GUID / external IDs from Plex Discover
* History + ratings: PMS items enriched with external IDs when available

{% hint style="warning" %}
Strict ID matching is the default.

If external IDs are missing, CrossWatch usually prefers a missing peer over a wrong match.

Use [Recover Plex history](/crosswatch/main-dashboard/tools/import-export/recover-plex-history.md) to import retained history for items no longer in your libraries.
{% endhint %}

### Watchlist behavior

* Read: pulls your watchlist from **Plex Discover**.
* Write: add/remove via Discover actions.
* No fuzzy title matching.

### Collection behavior

Plex is a Collection source only. Collection sync uses items in selected Plex libraries.

It does not read or write named Plex collections. Collection sync is one-way only.

### History behavior

* Read: PMS play history for the selected user.
* Write:
  * Add = mark watched (Plex uses current server time)
  * Remove = unscrobble

{% hint style="warning" %}
Plex has no supported way to **backdate** a play.

If CrossWatch writes **History** into Plex, Plex records `watched_at` as **now**.

This affects history sync and **History** capture restores.

That matters because when you later syncs history back from Plex to a tracker, CrossWatch send those Plex timestamps back to the tracker as if they were the real watch dates. This can overwrite the user’s historical watch timeline.
{% endhint %}

{% hint style="info" %}
Plex has “play history” and “marked watched”. Marked watched is optional and add-only. See below.
{% endhint %}

### Ratings behavior

* Read: scans libraries and keeps items with `userRating`.
* Write:
  * Add = rate (1–10)
  * Remove = clear rating (rating 0)

### Progress behavior

* Read: current resume position for items with progress.
* Write: set resume position (“Continue Watching”).
* Clear: not supported by Plex.
* Optional [Continue Watching removal sync](/crosswatch/settings/configure-pairs/features/progress.md#sync-continue-watching-removals) can hide a movie or matching episode while keeping its resume position. Both sides must be Emby, Plex, Tofa or Silo.

Related: [Progress](/crosswatch/settings/configure-pairs/features/progress.md).

### Friend and shared account behavior

When you select a Plex friend or shared user from the server owner’s profile, CrossWatch can try to use Plex’s server-scoped shared token for that user.

Support is limited:

* **History** — supported
* **Progress** — supported
* **Ratings** — not supported
* **Watchlist** — not supported
* **Playlists** — not supported

Ratings are blocked for shared users because Plex can return the server owner’s ratings instead of the shared user’s ratings.

Watchlist is blocked because Plex watchlist lives in account-level cloud data.

{% hint style="warning" %}
Use the owner’s Plex profile for shared-user history and progress only.

Use the friend’s own Plex login if you need watchlist or ratings.
{% endhint %}

### Settings (advanced)

<details>

<summary>Common keys and knobs</summary>

Workers:

* `plex.rating_workers` (1–64)
* `plex.history_workers` (1–64)

Library filters:

* `plex.ratings.libraries` (section IDs)
* `plex.history.libraries` (section IDs)

Watchlist:

* `plex.watchlist_query_limit`
* `plex.watchlist_write_delay_ms`
* `plex.watchlist_allow_pms_fallback`

History:

* `plex.history_ignore_local_guid`
* `plex.history_ignore_guid_prefixes` (example: `local://`)
* `plex.history_require_external_ids`
* `plex.history.include_marked_watched`

For retained history missing from your libraries, use [Recover Plex history](/crosswatch/main-dashboard/tools/import-export/recover-plex-history.md).

</details>

<details>

<summary>Marked Watched (Plex “checkmark”) behavior</summary>

Plex has two different signals:

* **Play history**: real play events
* **Marked watched**: manual “mark as watched” state

If `plex.history.include_marked_watched = true`:

* CW also scans your libraries for items Plex considers watched
* It merges those into history **only if Plex provides a timestamp** (`lastViewedAt` / `viewedAt`)

This is **add-only**:

* Mark watched in Plex → can sync out
* Unmark watched in Plex → CW will **not** unwatch on other services

{% hint style="warning" %}
Marked Watched is intended for the PMS owner. it will automatically be disabled when used for home users or friends.
{% endhint %}

</details>

### Diagnostics

<details>

<summary>Unresolved (freeze) files</summary>

Items that can’t be matched or written are frozen to avoid repeat retries:

* Watchlist: `/config/.cw_state/plex_watchlist.unresolved.json`
* History: `/config/.cw_state/plex_history.unresolved.json`
* Ratings: `/config/.cw_state/plex_ratings.unresolved.json`

</details>

### Notes and limitations

* Prefer external IDs and stable libraries.
* If `plex.baseurl` uses `https://`, the certificate must validate correctly from the CrossWatch container. Invalid or rejected certificates can cause `HTTPSConnectionPool` or `SSLError` failures.
* Friend/shared account support is best-effort.
* Shared-user support depends on Plex’s server-scoped token behavior and may change in the future.
* Selecting a friend from the owner’s Plex profile does not grant access to that friend’s personal watchlist or ratings data.
* Setup details: [Auth: Plex](/crosswatch/settings/connections/media-servers/plex.md).
* Start one-way. Run one feature. Then expand.

### Trakt rewatch resets

When paired with Trakt VIP, this server can follow show rewatch resets through the pair’s **History → Follow Trakt rewatch resets** option. It is off by default and can mark older episodes unwatched even if normal **Remove** is disabled. See [Trakt rewatch resets](/crosswatch/settings/configure-pairs/features/history/rewatches.md#follow-trakt-rewatch-resets) before enabling it.


---

# 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/media-servers/plex.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.
