> 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/settings/synchronization/trackers/myanimelist-mal.md).

# MyAnimeList (MAL)

Sync anime watchlists, ratings, and watched history with MyAnimeList.

Sync anime watchlists, ratings, and watched history with MyAnimeList. MAL can be a one-way source or destination, or participate in compatible two-way syncs.

{% hint style="warning" %}
MyAnimeList is an experimental, anime-only provider. Start with a one-way pair and use **Interactive Sync** to review changes before applying them.
{% endhint %}

### What CrossWatch can sync

| Feature    | Read | Write | Notes                                                                                           |
| ---------- | ---- | ----- | ----------------------------------------------------------------------------------------------- |
| Watchlist  | Yes  | Yes   | Anime movies and series in Plan to Watch.                                                       |
| History    | Yes  | Yes   | Watched anime movies and episode counts; requires Anime ID Mapping. No separate rewatch events. |
| Ratings    | Yes  | Yes   | Anime movies and series.                                                                        |
| Progress   | No   | No    | Resume positions are unsupported; watched episode counts use History.                           |
| Playlists  | No   | No    | Unsupported.                                                                                    |
| Collection | No   | No    | Unsupported.                                                                                    |

**Read** brings data into CrossWatch; **Write** sends changes to this provider. Enable only features supported by both sides.

**Anime-only sync** is always enabled for MyAnimeList watchlist, ratings and history. Manga is unsupported. Ratings use whole numbers from 1 to 10.

Connect the provider first: [MyAnimeList setup](https://wiki.crosswatch.app/crosswatch/settings/connections/trackers/myanimelist-mal.md).

### Prerequisite: connect MyAnimeList

Open **Settings → Connections → MyAnimeList**, select a connection profile, and click **Connect MyAnimeList**. Approve CrossWatch in your browser and wait for the connected account to appear. Authorization is saved automatically.

Guide: [MyAnimeList (MAL)](https://wiki.crosswatch.app/crosswatch/settings/connections/trackers/myanimelist-mal.md).

### How matching works

MyAnimeList identifies anime with MAL IDs. CrossWatch uses **Anime ID Mapping** to connect these to other providers and translate season and episode numbering.

* A valid MAL ID can identify an anime movie or series directly.
* Local mapping data can resolve other supported provider IDs to MAL IDs.
* Episode history needs mapping to translate source episodes into progress within the correct MAL entry. Mapping also translates MAL progress back to destination episodes when MAL is the source.
* Custom mappings can correct title identities, split seasons, cours, and episode ranges.
* The adapter does not search by title as a fallback. Unmatched or ambiguous items are skipped or reported as unresolved.

{% hint style="info" %}
Enable global **Anime ID Mapping** before syncing episode history or matching titles across providers. Check that its mapping data is available, especially when providers organize seasons differently.

Guide: [Anime ID Mapping](https://wiki.crosswatch.app/crosswatch/settings/connections/metadata/anime-id-mapping.md).
{% endhint %}

### Watchlist

The MAL watchlist corresponds to the **Plan to Watch** tab in your anime list. Titles marked Watching, Completed, On Hold, or Dropped are outside this watchlist.

Adding a missing title creates a **Plan to Watch** entry. If it already has another watch status, CrossWatch preserves that status instead of moving it back to Plan to Watch.

Removing a planned title deletes its list entry only when it has no other saved information. If it contains watched progress, a score, notes, tags, dates, or other list data, CrossWatch changes its status to **On Hold** instead.

### Ratings

Scores belong to anime movies and series, not individual seasons or episodes. MAL accepts whole-number scores from **1 to 10**.

Updating a score preserves existing watched progress and status. Removing a score clears it to zero without deleting the list entry. Scoring an anime that is not yet on the list creates an **On Hold** entry.

### History to MyAnimeList

MAL stores a cumulative watched episode count for each anime entry.

* CrossWatch maps each episode to its MAL entry and episode number.
* Adding history advances progress to the highest selected episode without lowering existing progress.
* Selecting episode 5 therefore marks episodes 1 through 5 watched.
* Reaching the known final episode of an anime that has finished airing sets **Completed**.
* Anime movies are marked **Completed**.
* Existing completed entries are preserved when adding history.

Episode additions are grouped by MAL entry within each write batch. CrossWatch sends the highest progress together and avoids updates when the stored values already match. This is grouped processing in CrossWatch, not a bulk MAL API request covering multiple titles.

#### Status mapping

Enable **History** and **Status mapping**, then review **Providers → Status mapping** before saving the pair. Saving with status mapping on creates default On hold and Dropped rules where both providers support them, even without editing a rule. Status changes can sync without new watched episodes; Completed destinations remain protected and status labels do not create watched plays.

#### Removing history

Enable **Remove** in the pair's History settings to allow supported removals. MAL can only reduce progress from the end of the watched range.

For a title with 10 watched episodes:

* Removing episodes 8, 9, and 10 reduces progress to 7.
* Removing episode 8 alone would leave a gap, so it is reported as unresolved.

A remaining watched count sets the title to **Watching**. Removing all watched episodes, or a movie's watched state, resets progress to zero and sets **On Hold**. Scores and notes remain. A completed title with an unknown episode total cannot safely have its history reduced until that total is available.

### History from MyAnimeList

CrossWatch expands the watched episode count into individual watched states and maps them to the destination. A completed anime with a known episode total contributes all its episodes. Watched anime movies are exported as watched movies.

These are derived states, not dated playback events. CrossWatch does not invent individual watch dates from MAL list-update timestamps. Destinations that require original watch-event dates cannot reconstruct those dates from MAL progress.

#### Watch dates and destination compatibility

MyAnimeList provides watched status and episode progress, not individual playback timestamps. CrossWatch exports this as watched state with an unknown watch date.

**CW Tracker, Trakt, SIMKL and WeTrakr** can preserve the unknown watch date. **AniList and Kitsu** accept mapped anime progress without inventing episode watch dates. Other destinations are skipped when CrossWatch cannot preserve the unknown date.

The skip explanation appears in Interactive Sync, Analyzer and Events. These rows cannot be selected for application. Changing a title mapping does not resolve an unknown-date restriction.

For SIMKL, **Replace unknown watch dates with today (SIMKL)** is off by default. Enable it in the pair's History settings only if you want SIMKL to record those watches as today. The MAL source stays undated. See [Unknown watch dates](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/features/history.md#unknown-watch-dates).

These limitations apply only to history syncing. Watchlist and rating syncing do not need watch timestamps.

{% hint style="info" %}
**Rewatches** and **Specials (Season 0)** are not supported as normal MAL history sync features. A cumulative episode count cannot represent gaps or separate repeat viewings.
{% endhint %}

### Snapshot model

CrossWatch reads the anime list in pages and derives watchlist, ratings, and history snapshots from it. The adapter does not use an incremental change feed.

List data is reused within a sync operation where available. An Interactive Sync review and its pre-apply recheck can still require separate reads. Writes are grouped by anime title where possible, so the number of proposed episode changes is not the number of API requests.

### Rate limits and token lifecycle

CrossWatch paces MAL API requests and handles rate-limit responses with retries and cooldowns. Large first syncs may take time. Request activity is recorded through the shared provider usage handling.

Access tokens refresh automatically through the CrossWatch authentication service. If refresh is rejected, reconnect the selected account under **Settings → Connections → MyAnimeList**. The CrossWatch server or Docker container needs outbound access to both the authentication service and the MAL API.

### Best practices

* Enable Anime ID Mapping and verify a few familiar anime before a large sync.
* Start one-way, then consider two-way sync after checking mappings and results.
* Review proposed removals and unresolved matches in Interactive Sync.
* Remember that adding a later episode also marks preceding episodes watched.
* Correct split seasons and episode ranges with custom mappings.
* Allow time for request pacing rather than repeatedly restarting a large sync.

### Custom status mapping

For per-pair status rules, enable History and **Status mapping**, then configure **Providers → Status mapping**. See [Status mapping](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/provider-settings/status-mapping.md) for supported movie/show destinations, defaults, and restrictions. Planned stays managed by Watchlist.


---

# 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/settings/synchronization/trackers/myanimelist-mal.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.
