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

# AniList

Sync anime watchlists, ratings and watch history with AniList.

Sync anime watchlists, ratings, and watched history with AniList. AniList can be the source or destination of a one-way sync. It can also participate in compatible two-way syncs.

### What CrossWatch can sync

| Feature    | Read | Write | Notes                                                                                           |
| ---------- | ---- | ----- | ----------------------------------------------------------------------------------------------- |
| Watchlist  | Yes  | Yes   | Anime movies and series in Planning.                                                            |
| 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 AniList watchlist, ratings and history. Manga is unsupported.

Connect the provider first: [AniList setup](https://wiki.crosswatch.app/crosswatch/settings/connections/trackers/anilist.md).

### Prerequisite: connect AniList

Connect your account under **Settings → Connections → AniList**. Save the connection before creating a sync pair.

Guide: [AniList](https://wiki.crosswatch.app/crosswatch/settings/connections/trackers/anilist.md).

### How matching works

AniList identifies anime with AniList IDs. It can also resolve MyAnimeList IDs. Other providers may use IMDb, TMDb, or TVDB IDs. CrossWatch uses **Anime ID Mapping** to bridge these IDs and translate episode numbering.

* Existing AniList IDs can identify titles directly.
* MyAnimeList IDs can be resolved through AniList.
* Anime ID Mapping can enrich titles with IDs understood by the destination provider.
* Episode mapping translates seasons and episodes into AniList progress. It also maps them back when AniList is the source.
* Custom mappings can correct title matches and episode ranges in either direction.

With anime-only sync enabled, unmatched items are skipped instead of falling back to a title search. Reverse sync needs IDs and episode coordinates that the destination can use. An AniList ID alone is insufficient for every provider.

{% hint style="info" %}
Enable global **Anime ID Mapping** before syncing history. History reads, additions, and removals require the mapping service to be enabled and available.

For watchlist and ratings, enable the pair's anime mapping option when matching across different ID systems.

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

### Watchlist

AniList's watchlist contains anime titles marked **Planning**. Watching, completed, paused, dropped, and repeating entries are outside this watchlist.

Adding a title sets its status to Planning. If the title already has another status, a watchlist addition can move it back to Planning.

Removing a title deletes its AniList list entry. This also removes attached information, including its rating and progress. Review watchlist removals carefully when the title also has ratings or history.

### Ratings

Ratings apply to anime movies and series, not individual episodes or seasons. CrossWatch reads ratings on a 1–10 scale and converts writes to AniList's score format.

Removing a rating clears the score without deleting the list entry. Rating writes do not explicitly change the existing watch status or progress.

### History to AniList

AniList stores one watched episode count per anime title. It does not store a separate event for every episode.

* Episodes map to the appropriate AniList title and episode number, including different season or cour splits.
* Adding history advances progress to the highest selected episode. It does not lower existing progress. Completed titles are left alone.
* Selecting episode 5 marks episodes 1 through 5 watched in AniList.
* Reaching a finished title's known final episode marks it **Completed**. Anime movies use the same completion logic.
* Available source watch dates fill a missing start date and set the completion date. When no source dates are available, CrossWatch updates progress without adding start or completion dates.

CrossWatch groups episode additions by AniList title within each write batch and updates progress together. A title spanning several batches may still need more than one update.

#### 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. AniList can reduce progress only from the watched range's end.

For example, with progress at episode 10:

* Removing episodes 8, 9, and 10 reduces progress to 7.
* Removing episode 8 alone leaves a gap, so CrossWatch reports it as unresolved.

When some watched episodes remain, the title becomes **Watching**. Removing all watched episodes, or resetting a movie to unwatched, sets progress to zero and the status to **Paused**. The completion date is cleared.

History removal preserves the list entry, rating, notes, start date, and repeat count. A completed series with an unknown episode total cannot be safely reduced. CrossWatch reports it as unresolved.

### History from AniList

CrossWatch expands AniList progress into watched episodes. It maps them to the destination provider. For completed titles, it also considers the known episode total. Watched movies are exported as movie history.

This supports reverse history sync to compatible providers, including SIMKL and Floppy, when required title IDs and episode mappings are available.

These are derived watched states, not individual playback records. CrossWatch uses the completion date when available. Otherwise, it uses the list entry's update or creation time. Episodes from the same title can therefore share a timestamp.

{% hint style="info" %}
**Rewatches** and **Specials (Season 0)** are unsupported by AniList history sync. Existing repeat information is not synchronized as separate watch events. The episode count cannot represent gaps.
{% endhint %}

### Snapshot model

AniList sync reads the current lists and builds snapshots for enabled features. Watchlist uses the Planning list. Ratings and history read relevant state across the anime library. These reads do not use an incremental change feed.

An Interactive Sync review and its pre-apply recheck can both read AniList. Proposed episode counts do not directly correspond to API request counts because history writes are grouped by title.

### Shadow state

CrossWatch keeps local watchlist state in `anilist_watchlist_shadow.json`. It records resolved AniList entries and source IDs. It also remembers ignored items to avoid repeatedly attempting unmatched additions.

This state stabilizes matches between runs. It supplements the live Planning snapshot. It is not a backup of the full AniList library.

### Rate limits and token lifecycle

CrossWatch paces AniList GraphQL requests and uses shared retry handling for rate limits and temporary failures. Large syncs can take longer while requests wait. Interactive Sync shows request activity.

AniList authentication does not use automatic refresh tokens in CrossWatch. If the access token expires or is revoked, reconnect the selected account under **Settings → Connections → AniList** and save it again.

### Best practices

* Enable Anime ID Mapping and check a few known titles before a large sync.
* Start with one-way sync. Enable two-way sync only after validating mappings and results.
* Use Interactive Sync to review proposed changes, especially watchlist deletions and history removals.
* Remember that adding a later episode marks preceding episodes watched in AniList.
* Use custom mappings for missing titles, split seasons, or incorrect episode numbering.

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

### Unknown watch dates

History read from this provider represents cumulative watched progress with an unknown watch date. CrossWatch does not turn list-update or title-level dates into individual episode watch dates. Only destinations that can preserve an unknown date can receive those watched states. See [Unknown watch dates and supported destinations](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/settings/synchronization/trackers/anilist.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.
