> 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 it supports * **Watchlist:** Add and remove anime movies and series from **Plan to Watch**. * **Ratings:** Add, update, and remove whole-number title scores from **1 to 10**. * **History:** Read watched anime movies and episode progress, advance progress, and apply supported removals. * **Connection profiles:** Choose which MyAnimeList account the pair uses. **Anime-only sync** is always enabled and locked for MyAnimeList watchlist, ratings, and history pairs. Non-anime items are excluded. Manga, playlists, collections, playback position, and resume syncing are unsupported. ### 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)](/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](/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. #### Use source watch status Enable **Use source watch status** in the pair's History options to preserve **Dropped** or **On Hold** when adding watched episodes between SIMKL, AniList, MyAnimeList, and Kitsu. Completed progress takes precedence. This option accompanies history writes: status-only changes and titles with no watched episodes do not create history changes. With the option disabled, normal destination progress rules determine the status. #### 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. {% 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. --- # 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=&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.