> 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/wetrakr.md).

# WeTrakr

WeTrakr adapter notes for syncing watchlist, history, ratings, and playback progress, playlists and My Library collections.

#### What CrossWatch can sync

| Feature    | Read | Write | Notes                                                                                  |
| ---------- | ---- | ----- | -------------------------------------------------------------------------------------- |
| Watchlist  | Yes  | Yes   | Movies and shows.                                                                      |
| History    | Yes  | Yes   | Movies and episodes; episode-zero records can be read but not written.                 |
| Ratings    | Yes  | Yes   | Movies, shows, seasons and episodes; episode-zero writes are unsupported.              |
| Progress   | Yes  | Yes   | Resume positions for movies and episodes; episode-zero writes are unsupported.         |
| Playlists  | Yes  | Yes   | Your own lists are writable; followed and liked lists are read-only.                   |
| Collection | Yes  | Yes   | My Library: movies and episodes, with media info and movie copies. One-way pairs only. |

**Read** brings data into CrossWatch; **Write** sends changes to this provider. Enable only features supported by both sides.

Ratings support 0 to 10 in tenths. A score of 0 is a rating, not a removal.

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

#### How matching works

CrossWatch uses **TMDb**, **IMDb**, and **TVDb** IDs, plus native WeTrakr IDs returned by the API.

Episode matching also uses the parent show IDs and season/episode numbers. Season ratings require the parent show and season number. Missing or unresolved IDs are reported in the sync results.

Progress writes require external IDs; a native WeTrakr ID alone is not enough.

#### Watchlist behavior

* Maps the CrossWatch watchlist to WeTrakr's **planning** status.
* Reads, adds, and removes movies and shows.
* Uses activity timestamps and incremental reads when possible, with full reads when needed to detect removals.

#### Ratings behavior

* Reads movie, show, season, and episode ratings.
* Supports new ratings, rating updates, and removing ratings.
* Reads each media type separately and verifies writes against the returned ratings.

#### History behavior

* Syncs watched movies and individual episodes, including available watch dates.
* With **Rewatches** disabled, syncs watched state rather than individual plays.
* With **Rewatches** enabled in the pair's History settings, syncs individual watch events and can remove a specific play.
* Rewatches are off by default and do **not** require WeTrakr VIP. The other provider must also support them and may have its own account requirements.

#### Progress behavior

* Syncs unfinished movie and episode playback positions.
* Skips changes that would overwrite active playback or newer target progress.
* Writes resume positions without marking the title watched.
* Handles ignored API responses as skipped operations instead of reporting them as applied.

#### Collection behavior

Collection reads and writes WeTrakr's **My Library**. Connect WeTrakr, create a one-way pair, enable **Collection**, and choose **Movies** or **Episodes**. Whole-show and season entries are not supported. Start with **Add** on and **Remove** off, then review the plan before applying it.

* Only owned library entries and copies are read; wanted or other non-owned entries are excluded.
* Movie copies can sync between a CW Tracker collection and WeTrakr, including format, video/audio, edition, packaging, condition, region and disc count. WeTrakr writes send at most the first **20 copies per movie**. A larger local copy list is not fully exported.
* Episode collection entries carry combined media information. They do not preserve a full list of individually editable copies like movies do. Episode-zero writes are unsupported.
* Sources without copy lists send one copy with available media info. For supported media servers, enable **Read from media server** in the pair to include it.
* Enable **Update existing items** to send changed media information and supported copy changes for existing collection entries. It is off by default.
* One-way removals target copies associated with that source provider/profile, so independent sources can coexist in My Library. Review removals before enabling **Remove**.

**Send private copy details** is off by default. Enable it in the pair's Collection options to send price, store, shelf location, notes and who borrowed a movie copy to WeTrakr. Purchase dates can be sent as collection dates even with this option off. Turning the option off does not erase private details already saved in WeTrakr. Reads can still bring available private details from WeTrakr into a CW Tracker.

When sending prices, CrossWatch uses the currency selected on the administrator's personal shelf. It does not convert amounts. Review currency labels before enabling private details, especially when importing purchases recorded in different currencies.

Collection sync uses copies stored in a [CW Tracker collection](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/cw-tracker.md#collection-copies-and-media-info), such as those brought in from WeTrakr. To manage WeTrakr copies, edit them in **My Library** and sync them into Tracker. **Add to my shelf** and **Edit on my shelf** in Tracker open the same [personal inventory](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/profile/my-shelf.md) as Hub; they do not edit synced copies or send personal shelf changes to WeTrakr.

#### Playlist behavior

When creating a list in Playlists, choose **Private** (default), **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).

Your own unlocked lists support reading, creation, rename, deletion, item changes, and ordering.

Followed, liked, and accessible public lists can be sources. Collaborators can add items, but cannot remove, reorder, rename, or delete lists.

Liked-list discovery does not include permission details. Resolving a supported list link can identify collaboration access. Locked lists and plan restrictions can limit availability.

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

#### Settings (advanced)

Configure the direction, connection profiles, enabled features, removal behavior, and optional rewatches on the pair under **Synchronization**. Dry runs preview changes without writing them.

<details>

<summary>Activity checks and journal use</summary>

Repeated synchronization and status checks can reuse unchanged account data to reduce API calls. CrossWatch refreshes data when provider activity changes or a write needs verification.

The journal is used selectively for history removals when rewatches are enabled and it reduces requests. CrossWatch checks the result and falls back to a full read when the journal is incomplete or inconsistent. Watchlist, ratings, and progress do not poll the journal.

</details>

<details>

<summary>Endpoints used</summary>

* Watchlist: `GET /sync/tracking/planning/{movies|shows}`
* Watched state: `GET /sync/tracking/watched/{movies|episodes}`
* Individual plays: `GET /sync/tracking/watched/history/{movies|episodes}`
* Ratings: `GET /sync/ratings/{movies|shows|seasons|episodes}`
* Progress: `GET /sync/tracking/playing/{movies|episodes}`
* Tracking writes: `POST /sync/tracking`, `/sync/tracking/remove`, and `/sync/tracking/remove/all`
* Individual play removal: `DELETE /sync/tracklogs/{id}`
* Rating writes: `POST /sync/ratings` and `/sync/ratings/remove`
* Progress updates and clear attempts: `POST /scrobble/pause`

</details>

<details>

<summary>Batching and API usage</summary>

Watchlist, history, and rating writes use batches of up to **500 items**. Individual play removals and progress writes use separate requests per item.

Reads currently use pages of **100 items**. Activity checks, ID resolution, and verification reads also consume API calls, so the total request count is higher than the number of write batches.

</details>

#### Diagnostics

**Unreadable history records**

If WeTrakr returns history records that CrossWatch cannot interpret, the History read fails. CrossWatch does not use the readable portion as a complete history list.

The error reports the total unreadable record count and identifies examples when available. Check the `WETRAKR:history` log for details of up to 20 records, including titles, IDs, episode numbers, and the reason. The short error message may show fewer records than the log.

Check the named records in WeTrakr. Typical causes include missing show information, invalid season or episode numbers, or missing play IDs or invalid dates for individual watch events. Correct the data where possible, or include the listed identifiers when reporting the problem. Then refresh the plan or run the pair again.

An Interactive Sync affected by this read failure excludes History proposals. Other features that finished planning can still be applied. See [Interactive Sync](https://wiki.crosswatch.app/crosswatch/main-dashboard/interactive-sync.md#if-a-feature-fails-during-planning).

<details>

<summary>Logging and quotas</summary>

Feature logs include `WETRAKR:watchlist`, `WETRAKR:history`, `WETRAKR:ratings`, and `WETRAKR:progress`. They report read counts, applied changes, skips, and unresolved items.

CrossWatch tracks rate-limit and daily quota headers and respects retry delays. The provider status tooltip shows remaining daily calls and the reset time when supplied by WeTrakr.

</details>

<details>

<summary>State and cache files</summary>

Snapshots are stored under `state/wetrakr/` inside the CrossWatch config directory, using hashed filenames. Caches are separated by account, connection profile, feature, and history mode.

Invalid, expired, or uncertain snapshots trigger a fresh read.

</details>

#### Notes and limitations

* The adapter is marked **experimental**.
* My Library sync supports movies and episodes; complete show/season entries and non-owned statuses are not supported.
* Whole-show and whole-season history are not supported; episode history is supported.
* Existing episode-zero records can be read, but episode-zero History, Ratings and Progress writes are rejected. Season 0 specials with episode numbers of 1 or higher are supported.
* Unverified writes remain unresolved so the sync does not silently report success.

### Custom status mapping

Titles explicitly reported with no tracking status, and titles in Waiting, are left unchanged and counted as excluded. Conflicting or unreadable statuses still need review. A pending, unconfirmed write is not cleared simply because the title is excluded.

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