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

# Captures

Create point-in-time captures for restore, compare, and scheduled retention workflows.

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

<figure><img src="https://565675962-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3rh5THg1PdhVsBt3GALo%2Fuploads%2F9YUWE7xOEzehVjRiv7Uw%2Fimage.png?alt=media&amp;token=49a3f808-63b2-4e9c-a465-8f0dd400faa4" alt=""><figcaption></figcaption></figure>

### 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
* CW 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 CW 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/settings/synchronization/media-servers/plex.md).
* 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

#### Title statuses in History captures

For providers that support [Status mapping](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/provider-settings/status-mapping.md), a **History** capture also saves available movie and show statuses. An **All** capture includes them through its History child. Statuses can be captured even when there are no watched plays.

Status capture requires a complete status read. If it fails, review the capture result rather than treating the History capture as complete. An older capture without status data still restores its regular feature data.

#### 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/settings/connections/library-whitelisting.md).

### 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**, CW 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 missing**: add missing feature data from the capture without wiping the target first
* **Replace**: clear the target feature first, then restore the captured data

{% hint style="warning" %}
CW 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.

That matters because when you later syncs history back from Plex to a tracker, CrossWatch send those Plex timestamps back to the tracker as if they were the real watch dates. This can overwrite the user’s historical watch timeline.
{% endhint %}

#### Restoring title statuses

When captured statuses are present, both **Merge missing** and **Replace** restore supported status values after the regular feature data succeeds. Merge missing can therefore update a title's status even when it adds no watched plays.

Status restore follows the same provider restrictions as [Status mapping](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/provider-settings/status-mapping.md#restrictions). Planned stays managed by Watchlist. Unsupported or unsafe status changes are excluded or reported for review; completion, active rewatches and other protected data are not overwritten to force a match. Restoring a status label does not create watched plays, although the regular History restore can add them.

Check the restore result for **restored**, **unchanged**, and **excluded** title-status counts and any errors. A pending unconfirmed status write must be resolved before regular feature data can be restored to that provider instance.

#### Restoring “All” captures

If the selected capture is a bundle (`feature = all`), Restore applies the chosen mode to each supported child feature. Captured statuses are restored only after all regular child restores succeed.

### 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/main-dashboard/navigation/captures/capture-compare.md) and [Capture Compare (Advanced)](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/captures/capture-compare-advanced.md).

### 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 → Scrobbler → Watcher routes → Plex ratings**
* **Settings → Scrobbler → Webhooks → Ratings**

Setup references:

* [Watcher](https://wiki.crosswatch.app/crosswatch/settings/scrobbler/watcher.md)
* [Webhooks](https://wiki.crosswatch.app/crosswatch/settings/scrobbler/webhooks.md)
  {% 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/settings/scheduling.md)

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

### Check capture activity

Open **Tools → Events → Captures** to review manual and scheduled capture results, failures and retention cleanup. Open a record for its provider profile, feature, trigger and available item count or failure reason. The record does not contain the capture itself. See [Events](https://wiki.crosswatch.app/crosswatch/main-dashboard/tools/events.md#captures-and-backups).

Select **View logs** on a record when available, or open **Tools → Logs → Captures** as an administrator, for the detailed log session.


---

# 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/navigation/captures.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.
