> 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/cw-tracker.md).

# Tracker

Browse your local tracker, log watches, keep notes, fix records, and import from connected services.

**Tracker** opens **CW Tracker**, CrossWatch’s own lightweight local tracker. Use it to log watches, manage ratings, watchlists, playback progress and collections, or keep personal notes about movies and shows. Your records are stored in your CrossWatch installation; no external tracker account is required.

Each CW Tracker instance has its own local records. Add records yourself, import them from a connected service, or fill the Tracker through configured sync pairs and scrobbling routes.

Use [Hub](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/profile.md) to browse and manage data across your connected provider accounts. Seeing a title there does not automatically add it to Tracker. Use **Tracker** when you want to keep and edit a local record of that title.

{% hint style="info" %}
Tracker changes are saved locally. Configured sync pairs can send additions, edits or removals to other providers on the next run. Read the affected-provider message before confirming a change. Personal notes and custom fields stay in CrossWatch.
{% endhint %}

{% tabs %}
{% tab title="End users" %}

### Get started

1. Open **Settings → Connections → Trackers → CrossWatch** and select **Connect local tracker**.
2. Open **Tracker** in the main navigation.
3. If you have several instances, choose one under **Title and tracker → Tracker** on desktop or **More → Tracker** on mobile.
4. Use **Log a watch**, **Import**, or a synchronization pair to add data.

Administrators can open the profile/avatar menu and choose **View as** to select a user profile, **All profiles**, or **Admin**. The default-instance view selects the default local Tracker and excludes named instances; it does not create a user profile. Selecting a profile scopes the available data and selects its assigned CW Tracker instance when available. The profile selector is separate from the local Tracker instance selector; it does not combine their records. Managed users stay within their assigned access.

Configure [TMDb Metadata](https://wiki.crosswatch.app/crosswatch/settings/connections/metadata/tmdb-metadata.md) for title search, artwork, episode information and cleanup checks. Connecting **TMDb (Sync)** alone does not configure metadata. You can add [Fanart.tv](https://wiki.crosswatch.app/crosswatch/settings/connections/metadata/fanart-tv.md) for optional logos and backgrounds; automatic posters and episode stills use TMDb. Administrators can [choose artwork per title](https://wiki.crosswatch.app/crosswatch/settings/connections/metadata/artwork-selection.md).

When you open a media details card from Tracker, its resume points and progress actions use only the selected local Tracker instance. For progress across connected providers, open [Hub → Progress](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/profile/playback.md).

### Find your data

Use the view tabs to switch between Tracker pages. Tabs that do not fit move into **More**. On mobile, the view bar stays available while scrolling, and **More → Tracker** selects the local instance. Mobile lists offer 10, 20 or 50 records per page, with 20 as the default; the mobile page size is remembered separately from desktop.

| Tab                 | What it shows                                                                                                                                            |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Overview**        | Continue watching, upcoming episodes and recently watched titles for the selected local Tracker.                                                         |
| **History**         | Recorded watches, with All, Movies and Shows filters and grouping by Watch or Title.                                                                     |
| **My titles**       | Movies and shows with notes, tags or custom-field values. A status or start/finish date alone does not add a title here. Filter by status, tag or title. |
| **Watchlist**       | Movies and shows saved for later.                                                                                                                        |
| **Ratings**         | Your local ratings.                                                                                                                                      |
| **Progress**        | Saved playback positions.                                                                                                                                |
| **Collection**      | Your local collection entries.                                                                                                                           |
| **More → Clean up** | Records that need matching or metadata review.                                                                                                           |

Switch between **List** and **Grid** using the layout buttons. The layout is remembered separately for each tab; History also keeps separate layouts for Watch and Title grouping. Search by title and use the available filters, sorting and page-size controls. On desktop, selecting a list row or grid card opens its title panel. On mobile, it opens the media details card, or the title sheet when a media card is unavailable. On smaller screens, expand **Title and tracker** to see the title panel; use **More → Tracker** for the instance selector.

Use **Filters** for local title status, tags and sorting. **No status** includes titles without a saved status. In History with **Group by → Watch**, **Only possible duplicates** finds entries with the same title, episode and watch time; different watch times remain separate. Compare the records before deleting anything. **Status labels on cards** is on by default and can be switched off here.

On mobile, **Saved views**, **Changes** and **Import** are in **More**, alongside the Tracker selector.

Use **Saved views** to save the current filters, layout and Tracker selection under a name. Up to 20 named views are stored in this browser. They are not shared with other browsers. Tracker also remembers your last browsing position.

The top statistics show recent plays, estimated hours and your day streak. Hours use known runtimes, so they can be incomplete until metadata has been checked. Show progress uses TMDb episode numbering; specials are excluded from the overall progress total. A next-episode suggestion follows your latest watched episode and may leave earlier gaps for you to review. The title panel can show upcoming or next-episode previews with artwork, air dates and summaries when TMDb information is available.

### Browse History by watch or title

Open **History**, then select **Filters** beside search. Choose **Type → All**, **Movies** or **Shows**, and set **Group by**:

| Group by  | What you see                                                                                                  |
| --------- | ------------------------------------------------------------------------------------------------------------- |
| **Watch** | Individual movie and episode plays, including rewatches. **By day** adds a date timeline.                     |
| **Title** | One entry per movie or series. Movie rewatches are grouped together; episodes are grouped under their series. |

For show progress and next-episode information, use **Type → Shows** with **Group by → Title**. This replaces the separate Shows tab. In this view, open **Filters** and use the **Hide dropped** checkbox beside **Status labels**. Show progress depends on available TMDb episode information.

A fresh browser starts with **All** and **Watch**. Your type, grouping and layout choices are remembered in this browser when you leave History or reload. Title grouping shares its List/Grid choice across All, Movies and Shows; Watch grouping keeps its own layout. **Clear filters** restores All and Watch, clears search and other filters, and turns status labels back on.

Selecting a grouped title opens its details. A grouped movie's **Edit latest watch** action changes the latest play, not every rewatch. Switch to **Watch** when you need to find a particular play.

{% hint style="warning" %}
Bulk removal in **Title** grouping selects titles, not individual plays. The **Watch history** choice removes all watches for those titles, including rewatches. Review the counts before confirming. **Everything for selected titles** also removes their ratings, watchlist entries, collections, progress and notes. You can undo the operation from **Changes**.
{% endhint %}

### Overview

**Overview** brings together **Continue watching**, **Airing soon**, and **Recently watched** for your selected Tracker. Continue watching uses saved playback progress or suggests the next unwatched episode from local history. Upcoming episodes need TMDb metadata; the calendar covers the next 30 days. Dropped shows are excluded from these suggestions.

Select a card to open its title, or use **…** for its actions. Mobile menus open as action sheets. The Continue watching actions let you mark the suggested item watched or mark the title Dropped. Recently watched includes **Log a watch**. Use **View all** to leave a preview: Continue watching opens **History** filtered to **Shows** and grouped by **Title** for next-episode suggestions, or **Progress** for saved playback. The header shows active playback when available and returns to Tracker statistics when it ends. To hide the current playback banner, close any open menu or dialog, then press **Escape**; if a title is selected, the first Escape clears that selection. Use **Show playback** to restore the banner. Dismissal applies to the current session, so a new playback session can appear again. It does not stop playback. Your selected tab is remembered for an hour; after that, Tracker opens Overview again.

### Month in review

Open **More → Month in review**, or select the monthly banner on Overview. Choose a month to see its plays, estimated watch time, movies, shows, longest streak and daily activity. The current month shows the month so far. Reports use this Tracker's local history and the configured scheduling timezone; watch time depends on available runtimes.

Use the movie/show and genre filters to explore the month. Open **Atmosphere** to choose a theme, hemisphere, holiday preferences or seasonal effects. These appearance choices are saved in this browser for the current user and Tracker.

Large reports can take time to prepare. You can leave the review and return from its ready notification. Administrators can turn reports off for an instance under **CrossWatch connection → Settings → Tracker options → Month in review reports**. This stops report generation and notifications while keeping saved reports.

### CrossWatch Wrapped

Open **More → CrossWatch Wrapped** for a yearly review of the selected local Tracker. Use **Year** to select a past year or the current year so far. It opens the previous year by default. In January, Overview can show a banner when the previous year's nonempty report is ready. Dismissing a review banner hides that period's banner for this user and Tracker in this browser; the report stays available from **More**.

Move through the eight chapters with **Previous scene**, **Next scene**, the chapter buttons, left/right arrow keys, or a horizontal swipe on touch screens. Explore watch totals, monthly and daily activity, most-played movies and series, your longest streak, viewing times, genres and rewatches. Select a title to open its media card.

The review uses local watch history and the configured scheduling timezone. Watch time is estimated from known runtimes; metadata gaps can leave statistics incomplete. Replays count extra watches of the same movie or episode within the selected year. Large reports prepare in the background, and the bell can notify you when a review you left is ready.

In the final **The keepsake** chapter, choose **Save your keepsake** to download a PNG summary. Your name is excluded by default; enable **Include \[name] on my keepsake** to add it.

Administrators can disable **CrossWatch Wrapped** under **CrossWatch connection → Settings → Tracker options**. It is on by default and independent of **Month in review reports**. Turning it off stops yearly report generation and notifications while retaining saved reports.

### Log watches and manage titles

1. Select **Log a watch**.
2. Search TMDb and choose the correct movie or show.
3. Choose the watched date. For a show, select a season and episode for a quick watch, or select **Manage episodes** for more options.
4. Confirm the watch.

You can also log an unwatched episode from the title panel, rate a title, or add it to your watchlist. Ratings support **0.5 to 10** in half-point steps. Hover over or focus a star to preview its numeric value; selecting it saves the rating in the dedicated rating dialog. When using **… → Edit rating** on an existing record, choose the half-star value and select **Save**; **Cancel** leaves the record unchanged. Recording a new watch does not automatically enable synchronization with another account.

Use **More add options** beside **Log a watch** to open [Quick Add](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/quick-add.md) for one-off actions to selected connected accounts. Log a watch saves to your selected local Tracker; Quick Add uses the destinations you choose.

For season and episode previews in the shared media card, see [Browse a show’s seasons](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/profile.md#browse-a-shows-seasons).

### Manage episode watches

After choosing a show in **Log a watch**, select **Manage episodes**. Choose **Mark episodes watched**, **Log a rewatch**, **Change watch dates**, or **Remove watches**, then select up to 200 eligible episodes across seasons.

For additions or date changes, choose **Now**, **Release date**, **Custom date**, or **Date range**. A date range spreads the selected episodes evenly in episode order. Release date needs available episode air dates. Future watch dates are not accepted.

For date changes and removals, choose **Latest watch only** or **All watches**. Changing all watch dates shifts earlier plays by the same amount as the latest play. **Log a rewatch** keeps earlier watches. When offered, **Remove from watchlist** also removes the local watchlist entry.

Review the affected episodes, dates and watch count before saving. If history changed while the editor was open, use **Reload history** and review again. Changes can be undone through **Changes**.

### Automatic statuses

**Automatic status updates** is enabled by default for each Tracker instance. New watch-history activity can set a watched movie to **Completed** and a show with regular watched episodes to **Watching**. A show becomes **Completed** only when saved TMDb information confirms it has ended or been canceled and all its regular episodes are watched. Specials do not complete a show; an ongoing show stays Watching even when you are caught up.

Manually chosen statuses, including **No status**, stay protected. Use **My notes → Use automatic status** to hand a title back to automatic management; this saves immediately without another **Save**. The button then reads **Automatic status is on**.

Older Watching statuses can be updated without opting in title by title. Other older saved statuses are retained. A synced Watching show can become Completed when updated metadata confirms completion; other synced statuses are kept during a library update until new watch activity. Notes, tags, dates and custom fields are preserved.

Open **More → Automatic statuses** and select **Update statuses** to check existing history, fill missing statuses and refresh eligible automatic ones. This saves eligible changes directly. You can close the window while it runs. It pauses during sync and resumes after a restart. **Stop update** keeps changes already made; **Update again** starts another check after completion. A library update starts only when requested.

Automatic processing uses saved history and cached metadata. Missing or incomplete show metadata can delay completion. Watching shows are checked again when their TMDb metadata changes; manually set statuses stay protected. Use **Changes** to inspect grouped automatic updates and undo individual titles. Status changes stay local unless a sync pair uses [Status mapping](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/provider-settings/status-mapping.md).

Administrators can disable **Automatic status updates** under **CrossWatch connection → Settings → Tracker options**. Re-enabling it does not start a whole-library review.

### Keep personal notes

Open a title and use **My notes → Add notes**, or its edit button for existing notes. You can also change status directly from the status control in the title panel. Choose **Watching**, **Plan to watch**, **Completed**, **On hold**, **Dropped**, or **No status**. Add **Started** and **Finished** dates, tags and notes, then select **Save**.

* Notes belong to the movie or show, rather than one individual watch.
* **My titles** collects titles with notes, tags or custom-field values. Status-only and date-only records remain saved but do not appear in this view. Setting Completed does not create watched episodes.
* Use **Add your own fields** or **Manage your fields** for Text, Number, Date, Yes / no, or Pick from a list fields. Fields are shared across titles within that Tracker instance.
* Changing a field type or removing a field clears its saved values. Review this before selecting **Save fields**.
* Use **Clear** to remove the personal information for a title. This does not delete its watched history.

To change several titles together, select their checkboxes, use **Visible** or **All results**, then choose **Set status**. Selecting episodes changes their parent show's status once. **No status** clears only the status; notes, tags, dates and custom fields remain. A status change does not add watched plays or change Watchlist membership.

In **My titles**, **Remove from My titles** removes the selected titles' personal details, including custom-field values. It keeps media records such as history and ratings. Both bulk actions can be undone through **Changes**.

Notes belong to the selected Tracker instance. Anyone with access to that instance can see them; use separate instances for separate journals.

When **All episodes watched. Apply Completed** appears in a title panel or editor, select it to set Completed manually. It does not add watched episodes.

You can save notes while a sync runs. Notes, tags and custom fields are not sent to other providers through normal synchronization. Personal status labels can be shared through optional [Status mapping](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/provider-settings/status-mapping.md); notes, tags, dates and custom fields remain local. The dropped-show import described below can also set a local Dropped status.

### Collection copies and media info

In **Collection**, open a title's menu and choose **Add to my shelf** or **Edit on my shelf**. This opens the same [personal shelf](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/profile/my-shelf.md) used by Hub. Copies, purchases, loans and shelf locations saved here belong to your signed-in user, not the selected Tracker instance. A TMDb match is required.

From a History record, **Add to collection** creates its local collection entry. It does not add a personal shelf entry or open the shelf editor. Add the title to your shelf separately from Collection if wanted.

Use **Covers** or **Shelf** alongside List and Grid layouts. **Shelf** shows movies and shows that are both in the selected Tracker collection and on your personal shelf, including Ordered or Wishlist entries without copies. It uses your personal shelf's formats, locations and copy counts. Use the other layouts to browse collection records not on your shelf, or Hub to browse your whole personal shelf. **Cases** switches between case artwork and plain covers.

Removing a personal shelf entry, including its last Owned copy, does not remove the Tracker collection record. Personal shelf changes do not sync to providers. Synced copies stored in Tracker remain separate: for example, [WeTrakr Collection sync](https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/wetrakr.md#collection-behavior) can bring in movie copies. The shelf editor does not edit those synced copies.

When editing a collection record, expand **Media info** to set format, resolution, HDR, audio, channels and 3D. Sync keeps your manual values. Select **Use synced values again** and save to let later syncs supply them again.

### Edit, match or delete records

Use the record actions to edit dates, ratings, playback percentage, title information or IDs. For a wrong match, use **Fix match** to select the correct title. Where offered, choose **Only this record** / **Only this episode** or **Every record of this title**.

Editing a whole title updates its related local records together. Dates, ratings and episode numbers remain unchanged when changing the title match; check episode numbering separately.

For a History record that was imported as a show or episode but is actually a movie, open **Fix match**, set **Match as → Movie**, search and select the movie, then save. This changes only that watch and preserves its date; it does not convert every episode of the show. An existing movie record is not overwritten. The correction is remembered for the same original watch in this Tracker, so importing it again does not recreate the old entry. Other episodes and later watches remain separate. Use **Changes → Undo** to reverse the correction.

Use **Where does this come from?** in the title panel to inspect available source information, including connected-service imports. Source information depends on saved records and your account access.

For a title-wide removal, use **Remove title** and choose **Watch history** or **Everything for selected titles**. Review the counts before confirming. Watch history removes plays and clears automatically managed statuses while retaining personal notes and manual statuses. Everything also removes the title’s other local records and personal details. Both can be undone through **Changes**.

Select records and choose **Delete** for a bulk removal. **All results** selects all records matching the filters across pages, so check the count before confirming. The confirmation explains whether a later sync can remove them elsewhere or add them back from another provider. No remote deletion occurs simply from pressing Delete in Tracker.

Open **Changes** to review what you logged, edited or deleted, filter the list, and use **Undo**. Undo is refused if the affected data has since changed or would overwrite another record. Refresh and review the current data instead. Undo changes local data; it does not immediately reverse a change already sent to another provider.

### Check and clean up matches

1. Configure your TMDb metadata key.
2. Open **More → Clean up** and select **Check all**.
3. Follow the background job in Tracker or the notification bell.
4. Review **Need attention**, **Not checked**, or **Match TMDB** results.
5. Correct a wrong match, use the offered TMDb title/year correction, or edit the record as needed.

Checks can use supported IMDb or TVDB IDs to look for a unique TMDb match when a TMDb ID is missing. They can flag missing IDs, unknown titles, title/year differences and episodes absent from TMDb. With global Anime ID Mapping enabled and a usable mapping available, anime checks and episode artwork use the mapped TMDb episode coordinates. Checks do not rewrite your records. A matching result is a comparison with TMDb, not a guarantee that an alternative episode order is correct.

**Stop** keeps results already collected. A restart can interrupt the check; run it again when ready. Authentication or connection problems can stop checks without proving that your records are wrong.

### Import from a connected service

1. Select **Import** in Tracker.
2. Choose the source account under **From**.
3. Select the supported features under **What to bring in**.
4. Under **How to import**, choose **Merge into an existing tracker** and select the **Tracker**. Administrators can instead choose **Import into a new tracker** and enter a **New tracker name**.
5. Leave **Review changes before importing** enabled and select **Review import**.
6. In Interactive Sync, check the proposed changes, select what to keep, then choose **Apply selected**. A new Tracker is created only when you apply the review.

This is a one-time, one-way import. It adds supported data without deleting destination records, writing back to the source, or saving an ongoing sync pair. Existing records may be updated according to the selected feature. Large histories can take time while IDs are matched.

Import review does not save mappings: correct imported matches in Tracker afterwards. Closing a review without applying it imports nothing. If global dry run is on, applying asks for confirmation to write the selected changes once; the global setting stays enabled.

For a direct background import, turn off **Review changes before importing** and select **Start import**. With this option, a new Tracker is created when the import starts.

When the source supports it, History imports offer **Also bring in shows you dropped**. This is off initially. Imported dropped shows receive a local Dropped status; review any existing personal status afterwards. A Dropped status alone does not make a show appear in **My titles**; that view requires notes, tags or custom-field values.

For background imports, you can leave the page and follow progress in the bell. **Stop** requests cancellation after the current batch; data already imported remains. Review the result for skipped, unresolved or failed items. Only one service import runs at a time, and it cannot start during another sync. You cannot import an instance into itself.

For an export file, use **Import a file** to open [Import / Export](https://wiki.crosswatch.app/crosswatch/main-dashboard/tools/import-export.md). File imports offer a preview before writing media records.
{% endtab %}

{% tab title="Power users" %}

### Access and limits

Managed users see Tracker only when they have write access and an assigned CrossWatch instance. They can access their assigned instances and source accounts; only administrators can create new instances. Read-only and monitor-only accounts do not have Tracker access.

Record changes cannot be saved while a sync runs; retry after it finishes. Use separate Tracker instances for independent local libraries. If editing is unavailable, ask your administrator to check the instance configuration.

Personal notes allow up to 10,000 characters and 30 tags per title. Custom fields are limited to 20 per instance. The local change log is retained for up to 90 days, subject to a 50,000-entry limit; it is not a permanent backup.

### Back up and restore

Use **Settings → Maintenance → CW Tracker → CW tracker archive → Download archive** for the selected instance. The portable archive includes tracker records, restore points, personal notes and custom-field definitions. It does not include the local Changes log.

**Import archive** accepts the supported tracker ZIP/JSON formats and can replace matching saved data. Select the correct instance and keep a backup first. This archive operation is different from importing a connected service.

For scheduled or encrypted backups, use **Backup & Restore**, select **CW trackers**, and choose all trackers or individual instances. **Recover one tracker as a new instance** restores a tracker into a separate instance without creating sync pairs.

See [Maintenance](https://wiki.crosswatch.app/crosswatch/settings/maintenance.md#cw-tracker-archive), [Backup & Restore](https://wiki.crosswatch.app/crosswatch/main-dashboard/tools/backup-and-restore.md), and [CrossWatch synchronization](https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/crosswatch.md) for restore and sync behavior.
{% endtab %}
{% endtabs %}

### Imported watches without dates

CW Tracker can keep watched states with an unknown date when syncing from supported providers, including cumulative anime progress. CrossWatch does not substitute today or a list-update date. Sending these watches onward depends on the destination; undated rewatch writes are skipped. See [Unknown watch dates](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/features/history.md#unknown-watch-dates).


---

# 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/cw-tracker.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.
