> 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 or Tautulli.

Recover older Plex watch events from either Plex or Tautulli and import them into the CrossWatch tracker.

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 or Tautulli.

You can also open this tool from **Interactive Sync** when Plex is selected.

{% hint style="info" %}
You can use **Plex** or **Tautulli** as the recovery source.

Plex reads the history stored by Plex itself.

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 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" %}
**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**
* **Tautulli**

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

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. Original episode numbers and watch dates remain unchanged.

Review suggestions carefully. 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.

**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 %}

### What recovery preserves

Recovered events are stored in the CW tracker using the standard history importer.

CrossWatch preserves:

* Original watch dates
* Separate rewatches
* Movie and episode identity
* Original season and episode numbers

Recovery itself does not run a sync pair.

Existing scheduled pairs using the CW tracker can synchronize the recovered history afterward.

### Plex or Tautulli?

Use **Plex** when the required history is still available directly from the Plex server.

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.

Tautulli is only a history source. CrossWatch does not write anything back to Tautulli.

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

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


---

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