> 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/main-dashboard/tools/import-export/recover-plex-history.md). # Recover Plex history Recover older Plex watch events from Plex, the Plex database or Tautulli. This tool is useful for movies and episodes that are no longer available in your Plex libraries, but where the original watch history still exists in Plex, the Plex database or Tautulli. You can also open this tool from **Interactive Sync** when Plex is selected. {% hint style="info" %} You can use **Plex**, **Plex database** or **Tautulli** as the recovery source. Plex reads the history stored by Plex itself. Plex database reads the same history straight from the Plex library database, including the Plex IDs stored with each play. Tautulli reads the Plex watch history previously recorded by Tautulli. {% endhint %} ### Before you start You need a **CrossWatch tracker profile** as the destination. For Plex recovery, you also need a configured Plex connection. For Plex database recovery, you need a configured Plex connection. When you upload a database file, the Plex account is only used to look up IDs. For Tautulli recovery, you need a configured Tautulli connection. {% hint style="warning" %} **Plex source** Plex server owner access is required. Recovery reads the server's full play history. Shared or managed user connections may not expose it. {% endhint %} {% hint style="warning" %} **Plex database source** **Download from the Plex server** requires Plex server owner access. CrossWatch downloads a copy of the server database, reads it and deletes the copy when the scan ends. **Upload a database file** works without server access, for example for an old or retired server. Upload the Plex library database, a Plex database backup or the ZIP from **Download database** in Plex. Files up to 16 GB are supported. {% endhint %} {% hint style="warning" %} **Tautulli source** Tautulli can only provide history that it recorded while Tautulli was running and history logging was enabled. It cannot recreate watches from before it was installed. {% endhint %} {% stepper %} {% step %} ### Choose the source and destination Select the recovery source: * **Plex** * **Plex database** * **Tautulli** For **Plex database**, choose **Download from the Plex server** or **Upload a database file**. When uploading, select **Choose database file**. After the upload, select the account to recover under **Plex account in the database**. Your own Plex user is selected when CrossWatch finds it. Then select the corresponding Plex or Tautulli connection and the **CrossWatch tracker profile** that will receive the recovered history. {% endstep %} {% step %} ### Scan history Select **Scan older history**. When **Plex** is used, CrossWatch reads the Plex user's configured history scope, checks accessible libraries and excludes items that are still available in Plex. When **Plex database** is used, CrossWatch reads the watch history stored in the database and keeps only plays of items that are no longer in your libraries. History from deleted libraries is included. Titles that were added back to Plex are skipped. Database recovery first uses stored GUIDs and external IDs. It supports HAMA TVDB GUIDs and AniDB GUIDs, including older HAMA GUIDs containing a bare AniDB ID. CrossWatch uses its locally available anime episode mappings to translate supported AniDB episodes into TVDB or TMDB season and episode coordinates. When ordinary database entries cannot be resolved by ID, CrossWatch can search Plex's catalog by title. These title-search suggestions require review before import. When **Tautulli** is used, CrossWatch reads the history recorded by Tautulli. Movies and episodes are imported from the Tautulli history API. Partial playback is ignored and resumed playback is grouped so a single viewing is not incorrectly treated as multiple watches. CrossWatch uses the playback completion time as the watch date. Where possible, existing Plex GUIDs and external IDs are used to identify the item. Missing metadata can be enriched through Tautulli before the event is added to the recovery preview. {% endstep %} {% step %} ### Resolve unmatched items Plex catalog title suggestions can already appear after a database scan, before you select **Match unresolved items**. Select **Match unresolved items** and choose a configured search provider. Then use **Auto match**. {% hint style="warning" %} Be careful when matching or auto-matching large result sets. Each movie may require an API request. For example, matching 2,000 movies can require up to 2,000 API requests. {% endhint %} Movies and series are grouped. One confirmed series match covers its unresolved episodes and rewatches. Watch dates remain unchanged. Episode coordinates normally remain unchanged, except where HAMA recovery uses explicit anime mappings. Review suggestions carefully. Review both the identity and episode coordinates before importing. Choose ambiguous matches manually. You can retry unresolved titles with another provider and select **Save checked matches** to update the recovery preview. Saving matches does not import anything. You can also select **Edit match** for an individual event to enter IDs or correct season and episode numbers. {% endstep %} {% step %} ### Select events Select the events to import. Nothing is selected automatically. **Select all matching** skips unreviewed title guesses. Selecting a guessed event individually confirms it. Review both the identity and episode coordinates before importing. **Duplicate in scan** means another recovered event has the same matched identity and watch timestamp. {% endstep %} {% step %} ### Import history Select **Import selected history**. CrossWatch skips invalid events, duplicates and events that already exist in the CW tracker. {% endstep %} {% step %} ### Review imported events Optionally select **Open imported items in Editor**. This opens only the events imported by this recovery. Use the existing **Send** action when you are ready to send the recovered history to another provider. {% endstep %} {% endstepper %} ### HAMA anime recovery HAMA history can contain different IDs or episode numbers in the episode GUID and stored parent metadata. For supported HAMA episodes, CrossWatch uses the episode GUID's identity. For AniDB entries, explicit episode mappings determine the corresponding TVDB or TMDB season and episode. This can change recovered episode coordinates while preserving the original watch date. Specials require an explicit mapping. Missing or ambiguous mappings, unsupported GUID formats, and unsupported extras remain unresolved. HAMA episodes without a usable mapping are not automatically assigned a Plex title-search match. A matching series title does not establish correct episode numbering. Use **Edit match** to supply or correct the identity and episode coordinates when necessary. This support applies to the **Plex database** recovery source. It does not recover every HAMA title or extra automatically. ### What recovery preserves Recovered events are stored in the CW tracker using the standard history importer. CrossWatch preserves: * Watch dates * Movie and episode identity * Episode coordinates, unless HAMA recovery converts them through the episode GUID and explicit anime mappings Repeated plays of the same movie or episode are combined into one event using the most recent watch date. Watch dates are preserved. Episode coordinates normally remain unchanged, but HAMA recovery can use the episode GUID and explicit anime mappings to convert them to the matched TVDB or TMDB numbering. Confirming a series title suggestion does not itself translate anime episode numbering. Recovery itself does not write anything back to Plex or Tautulli. A separately configured sync pair can send the recovered CW tracker history onward. ### Sending recovered history to Plex Discover Recovery imports history into the CW tracker. It does not itself write watched state back to Plex. Normally, writing history to a Plex server requires the movie or episode in that server's library. An optional pair setting can instead write watched state to the connected Plex account for items missing from the server. #### Enable the optional fallback In a sync pair that writes history to Plex, open **History → Plex → Plex Discover watched-state fallback**. The option is **off by default** and applies only to that pair. Enabling it also turns off **Only items in destination library** for the pair. Turning that filter back on prevents missing items from reaching the fallback. #### How it works * Items found on the destination server continue through the normal Plex history writer. * Missing movies and episodes can be matched in Plex's online catalog using external IDs. * Episodes require the corresponding season and episode in that catalog. * Ambiguous matches remain unresolved. * Items found elsewhere on the server, outside the pair's selected libraries, are not written through the cloud fallback. #### Watch dates and retries Plex initially records the current time when an item is marked watched. CrossWatch then updates the newly created history entry to the source watch date. These are separate requests. If the date update fails, Plex may temporarily show today's date. CrossWatch retains pending date updates across restarts and reports unfinished items as unresolved. Retry the affected item with the fallback enabled. If the new play cannot be identified uniquely, CrossWatch leaves it unresolved rather than editing another play. Date updates are limited to six attempts per 61 seconds per account. Server rate limits are also respected. Remaining items can be retried after the limit expires. #### Limits * Supports additions only. * Does not remove cloud plays. * Does not add rewatches to already watched items. * Does not change existing cloud watch dates. * Does not support managed accounts or switched Plex users. * Turning the option off stops further cloud writes and pending repairs. It does not undo completed writes. * Uses undocumented Plex account APIs, which may change. Importing recovered history does not automatically enable or run this fallback. ### Plex, Plex database or Tautulli? Use **Plex** when the required history is still available directly from the Plex server. Use **Plex database** when the items were removed from Plex. Plex no longer returns IDs for removed items through its history, so the Plex source has to match them by title. The database retains stored GUIDs, allowing many items to be identified directly. Supported HAMA episodes can also be resolved through explicit episode mappings. When ordinary entries cannot be identified by ID, Plex catalog title suggestions may be offered for review. Upload a database file when the server is gone or you only have a backup. Use **Tautulli** when you have an existing Tautulli history database that contains older Plex watches you want to recover. Tautulli can be especially useful when an item has been removed from Plex but its old watch records are still present in Tautulli. Plex database and Tautulli are only history sources. Recovery itself does not write anything back to Plex or Tautulli. A separately configured sync pair can send the recovered CW tracker history onward. ### Limits and temporary data Recovery can only restore history that still exists in the selected source. For Plex, Plex must still retain the original play history record. For Plex database, the database must still contain the play. Uploaded files can be up to 16 GB. Very large or damaged databases may be refused. Supported HAMA entries can now be matched automatically when suitable episode mappings are available. Unmapped or ambiguous anime entries, unsupported extras, and items without usable identity information still require manual matching. Ratings are not recovered. Items only marked watched in the database, with no recorded play, are not recovered. Missing watch dates cannot be reconstructed. For Tautulli, Tautulli must have recorded the play. Tautulli cannot provide history from before it was installed or from periods where history logging was disabled. Old Tautulli records may reference Plex items that no longer exist. In that case metadata enrichment may not be possible and the item may need to be matched using a search provider. Events without a usable watch date cannot be imported. A failed or cancelled scan imports nothing. Scan previews, unsaved suggestions and the Editor batch shortcut are temporary. Recovery previews expire after inactivity or an application restart. Imported history remains in the CW tracker. Downloaded database copies are deleted when the scan ends. Uploaded database files are deleted after the scan, or after one hour if no scan is started. ### Replaces Fallback GUID The former **Fallback GUID** pair option has been removed. Old configuration keys remain for compatibility with existing identity and cache keys. They no longer enable title searches during regular history or ratings syncs. Previously cached identity matches remain usable. **Plex Discover watched-state fallback** is a separate opt-in feature for writing account-level watched state. It does not restore the old title-matching option for regular syncs. --- # 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/main-dashboard/tools/import-export/recover-plex-history.md?ask=&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.