Captures

Rollback tool for provider watchlist, ratings, and history (not a full backup).

Captures are a rollback tool.

A capture exports a provider dataset so you can restore it later.

Older builds called this feature Snapshots.

Captures are a new, experimental feature. Use with care. Validate restores before doing destructive changes. Create a backup first. Check your media server/trackers for the right backup strategy.

Captures are not backups

Captures are not the same as a full backup.

They are a best-effort export of:

• one provider

• one dataset (Watchlist, Ratings, History)

They do not include:

• provider credentials or tokens

• CrossWatch configuration

• Items outside the scope of the sync adapter

  • For example: History items without a date won’t be included in a capture, but the process can still clear them.

  • Plex note: this often means items that are only Marked Watched (the Plex “checkmark”) without a usable viewedAt / lastViewedAt.

    • If you want CrossWatch to also scan “Marked Watched” state, set plex.history.include_marked_watched = true.

    • This is still best-effort. Items without timestamps can’t be exported into a history capture.

    • More detail: Adapter: Plex.

• everything your provider may store (notes, list metadata, privacy settings, etc.)

If you want a real backup, prefer provider-native export/backup features. Captures are the fallback when those are missing.

What captures are good for

Use captures before you:

• run destructive tools (clear watchlist/ratings/history)

• clean up lists in bulk

• migrate accounts

What a capture contains

A capture is a JSON export of one provider and one feature (or All features).

It includes:

• provider id (example: PLEX, TRAKT, SIMKL, ANILIST)

• feature (watchlist, ratings, history, or all)

• created timestamp and optional label

• basic stats (counts and media-type breakdown where available)

• the raw items needed to restore back into the same provider

Whitelisting impacts captures (media servers)

For Plex/Jellyfin/Emby, captures follow your library whitelists.

If you whitelist specific libraries for a feature, the capture includes only items from those libraries.

Example:

• History whitelist = only those libraries are exported in a History capture.

• Ratings whitelist = only those libraries are exported in a Ratings capture.

If you don’t configure whitelisting, captures include all visible libraries.

Guide: Library Whitelisting.

Where captures are stored

Captures are written to:

/config/snapshots/YYYY-MM-DD/

This folder name is legacy. It may still say snapshots on disk.

Filenames include a UTC timestamp, provider, feature, and optional label:

2026-01-27T19-12-45Z__TRAKT__watchlist__before-cleanup.json

“All features” captures

If you choose All features, CrossWatch creates:

• one bundle capture (__all__) that references child captures

• one child capture per supported feature (watchlist/ratings/history)

This keeps restore behavior predictable. It also lets you restore one dataset later.

Create a capture

1. Open Captures.

2. Select a Provider.

3. Select a Feature (Watchlist, Ratings, History, or All features).

4. Optional: set a Label.

5. Click Create capture.

Use short labels like before-import or after-cleanup.

Select and inspect captures

• The capture list shows up to 5 items by default.

• Click Show all to see everything.

• Click a capture to load its stats into the Restore panel.

• Click it again to clear the selection.

Capture Compare (diff)

Capture Compare gives you a deterministic diff between two capture files from the same provider.

Use it to answer: “What changed between capture A and capture B?”

It does not answer: “Which provider is correct?” or “What should sync?”

Open: Captures → Compare, then pick two captures and run the diff.

Compare is designed for same provider + same feature (watchlist vs watchlist, etc.).

Compare shows:

• Added: in B, not in A

• Removed: in A, not in B

• Updated: same key, payload changed

• Unchanged: same key, payload identical

More detail: Capture Compare and Capture Compare (Advanced).

Restore a capture

Select a capture, then choose a restore mode.

Restores write to the provider. Pick the mode carefully.

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.

Merge (safe default)

Merge adds items from the capture that are missing on the provider.

It does not remove items that exist on the provider already.

Clear + restore (destructive)

Clear + restore first clears the provider dataset (watchlist/ratings/history).

Then it restores the capture so the provider matches it as closely as possible.

This can delete a lot of data. Create a backup first. Check your media server/trackers for the right backup strategy.

Restoring “All features”

If the selected capture is a bundle (feature = all), Restore applies the chosen mode to each supported child feature.

Provider tools (destructive)

Tools run directly against the provider.

Available tools depend on what the selected provider supports:

• Clear watchlist

• Clear ratings

• Clear history

• Clear all

Clear ratings trigger rating-scrobble listeners.

If you enabled rating scrobbling, this can instantly send “unrate” events.

That can wipe ratings on attached providers too (example: Trakt).

Before using Clear ratings, disable rating scrobbling first:

• Settings → Scrobble → Watcher → Ratings (Plex only)

• Settings → Scrobble → Webhook → Enable ratings (legacy)

Setup references:

• Watcher

• Webhooks

If a provider doesn’t support a feature, that tool is disabled.

Typical workflow:

1. Create a capture

2. Run a clear tool

3. Optional: restore a capture

Deleting captures

Captures can be deleted from the UI.

• Select a capture

• Click Delete

• Confirm

If you delete an All features bundle, CrossWatch also deletes its child captures.

This only deletes files on disk under /config/snapshots/.... It does not touch provider data.

Notes and limitations

• Providers differ. A restore can be best-effort, depending on provider APIs.

• If a feature/tool is disabled, the provider does not support it (or is not configured).

• Captures are local files. If you move hosts, copy /config/snapshots too.

• Don’t forget: this is not a backup tool.