# Captures
Captures are a **rollback tool**.
A capture stores a point-in-time copy of provider data so you can restore it later.
You can also compare captures or keep scheduled backup-style snapshots over time.
Older builds called this feature **Snapshots**.
{% hint style="warning" %}
Captures are **experimental** and will stay experimental.
They are **not** a core CrossWatch feature. They’re a nice-to-have service.
Treat captures as best-effort:
* Use with care.
* Validate restores before doing destructive changes.
* Create a real backup first. Use your provider’s native export/backup
{% endhint %}
### Captures are not backups
Captures are **not** the same as a full backup.
They are a best-effort copy of:
* one **provider**
* one **profile**
* one **dataset** (Watchlist, Ratings, History, Progress)
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](https://wiki.crosswatch.app/crosswatch/providers/synchronization/adapter-plex).
* everything your provider may store (notes, list metadata, privacy settings, etc.)
{% hint style="info" %}
If you want a real backup, prefer provider-native export/backup features. Captures are the fallback when those are missing.
{% endhint %}
### 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**, **one profile**, and **one feature**.
You can also capture **All** features together.
It includes:
* provider id (example: `PLEX`, `TRAKT`, `SIMKL`, `ANILIST`)
* provider profile or instance
* feature (`watchlist`, `ratings`, `history`, `progress`, 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](https://wiki.crosswatch.app/crosswatch/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” captures
If you choose **All**, CrossWatch creates:
* one full capture bundle (`__all__`) that references child captures
* one child capture per supported feature
This is useful when you want one complete restore point across multiple features.
It also keeps restore behavior predictable and lets you restore one feature later.
### Create Capture
The Create Capture section lets you create a new capture manually.
#### Main options
* **Provider**: choose the source provider
* **Profile**: choose the provider profile or instance
* **Feature**: choose one feature or **All**
* **Label**: optional custom name for the capture
#### Available actions
* **Create capture**: create the capture immediately
* **Queue for scheduler**: send the current setup into Capture Scheduling
Use **Queue for scheduler** when you want to turn a one-off setup into a recurring automated capture.
{% hint style="info" %}
Use short labels like `before-import` or `after-cleanup`.
{% endhint %}
### Capture Browser
The Capture Browser shows all saved captures in one place.
You can:
* search by provider, feature, label, or path
* filter by provider
* filter by feature
* filter by type:
* **Manual**: captures created manually
* **Auto**: captures created by Capture Scheduling
For full captures, the browser can group and show child captures under the main **All** capture.
Click a capture to load it into **Restore** or **Compare**.
Click it again to clear the selection.
### Restore
Restore applies a saved capture back into a provider profile.
#### Restore modes
* **Merge**: add missing data from the capture without wiping the target first
* **Clear restore**: clear the target feature first, then restore the captured data
{% hint style="warning" %}
CrossWatch restores what was captured.
The target media server or tracker may still interpret that data differently afterward.
{% endhint %}
{% 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.
{% endhint %}
#### Restoring “All” captures
If the selected capture is a bundle (`feature = all`), Restore applies the chosen mode to each supported child feature.
### Compare
Compare lets you select two matching captures and see what changed.
#### Rules
* both captures must belong to the same provider
* you can compare two single-feature captures
* you can compare two **All** capture bundles that contain multiple features
This is useful for checking:
* items added
* items removed
* items updated
Compare is designed to answer: “What changed between capture A and capture B?”
It does **not** answer: “Which provider is correct?” or “What should sync?”
More detail: [Capture Compare](https://wiki.crosswatch.app/crosswatch/tools/captures/capture-compare) and [Capture Compare (Advanced)](https://wiki.crosswatch.app/crosswatch/tools/captures/capture-compare-advanced).
### Tools
The Tools area provides cleanup and maintenance actions for provider features.
That includes clearing supported feature data directly from the target provider.
{% hint style="danger" %}
Provider tools write directly to the provider. Use them carefully.
{% endhint %}
Available tools depend on what the selected provider supports:
* Clear watchlist
* Clear ratings
* Clear history
* Clear progress
* Clear all
{% hint style="warning" %}
**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](https://wiki.crosswatch.app/crosswatch/scrobble/watcher)
* [Webhooks](https://wiki.crosswatch.app/crosswatch/scrobble/webhooks)
{% endhint %}
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
### Scheduler Integration
Captures now work much more closely with scheduling.
You can:
* create a capture manually right now
* queue that setup directly into Capture Scheduling
That means a manual capture setup can become a repeating automated capture schedule without re-entering the provider, profile, and feature.
Related: [Scheduling](https://wiki.crosswatch.app/crosswatch/scheduling)
### Scheduled Capture Retention
Capture schedules can manage retention automatically.
Available options:
* **Label template**: define how scheduled captures are named
* **Keep captures for days**: delete captures older than a set age
* **Max captures to keep**: keep only the newest number of captures
* **Cleanup**: enable automatic pruning after each successful scheduled capture
So Captures now support:
* manual restore points
* scheduled recurring backup-style captures
* compare and restore workflows
* automatic retention cleanup for scheduled captures
### 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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://wiki.crosswatch.app/crosswatch/tools/captures.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.
