# Syncing

Syncing aligns watchlists, history, and ratings between services. Start small. Scale up after the first clean run.

{% hint style="warning" %}
Save changes often. Most settings do nothing until you click the **red floating Save button**.
{% endhint %}

### 1) Connect authentication providers

Open **Settings → Authentication**. Connect only what you need.

Start with:

* One media server: Plex, Jellyfin, or Emby
* One tracker: Trakt, SIMKL, MDBList, etc.

Click the **red Save button**.

Related: [Authentication](/crosswatch/providers/authentication.md)

### 2) Create one pair

Open **Settings → Pairs**. Create **one pair** first.

Use the safest setup. Keep defaults unless you know why you’re changing them.

{% hint style="info" %}
Golden rule: start **one-way**, with **one feature** enabled.
{% endhint %}

{% hint style="warning" %}
Two-way sync is not the default for a reason.

It can propagate conflicts, duplicates, overwrites, and deletes across both sides.

For most users, **one-way** stays safer and more predictable.
{% endhint %}

Recommended first run

* Mode: **One-way**
* Feature: enable **one**
  * Watchlist
  * Ratings
  * History
  * Progress (Plex/Emby/Jellyfin pairs only)
* Source: your media server
* Target: your tracker

{% hint style="info" %}
Progress only appears for **Plex/Emby/Jellyfin ↔ Plex/Emby/Jellyfin** pairs.

It does not apply when your target is a tracker (Trakt/SIMKL/MDBList/etc).
{% endhint %}

{% hint style="warning" %}
Do not start with “everything”. Run one feature first. Then add more.
{% endhint %}

Keep **Dry run** enabled at first. It previews the plan without writing changes.

Click the **red Save button**.

Related: [Configure Pairs](/crosswatch/configure-pairs.md)

### 3) Add metadata (recommended)

Open **Settings → Metadata**. Add **TMDb** (API key).

This improves matching. It also reduces missing peers.

Click the **red Save button**.

Related: [Metadata](/crosswatch/providers/metadata.md)

### 4) Run a sync

Run a sync. Review results. Fix matching issues. Repeat.

If the run ends with a line like `Done. Total added: ...`, see: [Sync results (added/removed/skipped)](/getting-started/first-time-setup/what-do-you-need/syncing/sync-results.md)

Use these tools when something looks off:

* [Analyzer](/crosswatch/tools/analyzer.md) for missing peers and mismatches
* [Editor](/crosswatch/tools/editor.md) for overrides, blocks, and cleanup

{% hint style="success" %}
Once your first pair is stable, add the next feature or pair.
{% endhint %}

### Related topics

* [Webhook or Watcher](/getting-started/first-time-setup/what-do-you-need/webhook-or-watcher.md) — real-time scrobbling instead of periodic syncing.
* [Best practices](/getting-started/best-practices.md) — recommended sync layouts.
* [CW Orchestrator](/blueprint-architecture/orchestrator.md) — how planning and applying works.
* [Scheduling](/crosswatch/scheduling.md) — run pairs on a cadence.

### Summary

Syncing aligns watchlists, history, and ratings between providers.

Start with one-way + one feature + dry run.

Add TMDb early to avoid bad matches.

### Next steps

* Configure feature toggles and guardrails: [Configure Pairs](/crosswatch/configure-pairs.md)
* Improve matching quality: [Metadata](/crosswatch/providers/metadata.md)
* Automate runs safely: [Scheduling](/crosswatch/scheduling.md)
* Diagnose missing peers and IDs: [Analyzer](/crosswatch/tools/analyzer.md)


---

# 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/getting-started/first-time-setup/what-do-you-need/syncing.md?ask=<question>
```

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.