> 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/blueprint-architecture/sync/_mod_anilist/ratings.md).

# ratings

AniList ratings are supported by this sync module.

Related:

* Pair setting: [Ratings](/crosswatch/configure-pairs/features/ratings.md)
* Pair options: [AniList pair options](/crosswatch/configure-pairs/anilist-pair-options.md)
* Matching: [Anime ID Mapping](/crosswatch/providers/metadata-id-mapping/anime-id-mapping.md)
* Engine semantics: [Ratings (engine-level)](/blueprint-architecture/sync/engine-level-features/ratings.md)

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

### What syncs

This feature syncs ratings between AniList and another supported provider.

AniList ratings are media-level ratings.

CrossWatch maps AniList anime entries to **movies** or **shows**.

Seasons and episodes are not supported.

### Supported media types

* Movies: supported
* Shows: supported
* Seasons: not supported
* Episodes: not supported

AniList entries with the `MOVIE` format map to movies.

TV, ONA, and OVA entries usually map to shows.

### Reads vs writes

* Reads: fetch rated AniList entries.
* Writes:
  * `add` creates or updates the rating.
  * `remove` clears the rating.

Clearing a rating does not delete the AniList list entry.

It only clears the score.

### Rating values

AniList ratings are read in the `POINT_10` format.

CrossWatch normalizes them to whole values from `1` through `10`.

When CrossWatch writes to AniList, it converts the value to `scoreRaw`.

Examples:

* `1` → `10`
* `5` → `50`
* `10` → `100`

Ratings from a `1` through `100` source scale are converted before write.

Missing, zero, negative, or invalid ratings are skipped.

### Matching note

Enable **Anime ID Mapping** for AniList pairs.

It improves cross-provider matches when the other side uses TMDb, TVDb, or IMDb IDs.

Guide: [Anime ID Mapping](/crosswatch/providers/metadata-id-mapping/anime-id-mapping.md)

When **Anime-only sync** is on, CrossWatch writes only items that resolve through AniList or MAL IDs.

Items that would need title search are skipped.

### Backfill note

This module reads all currently rated AniList entries.

AniList does not expose provider-side ratings filtering by date.
{% endtab %}

{% tab title="Power users" %}

### Index behavior

CrossWatch queries AniList `MediaListCollection` for the authenticated user.

Only entries with a valid rating enter the ratings index.

Each indexed item can include:

* `type`
* `title`
* `year`
* `rating`
* `rated_at`
* `ids.anilist`
* `ids.mal`
* AniList list entry metadata

Title preference order:

1. English
2. Romaji
3. Native

`rated_at` uses the AniList update timestamp when present.

Otherwise, it falls back to the entry creation timestamp.

The index uses `present` semantics.

AniList does not expose observed rating deletion events.

### Resolution order

Before CrossWatch writes a rating to AniList, it resolves the target in this order:

1. Existing AniList ID
2. Existing or mapped MAL ID
3. AniList title search

Title search uses title, year, and media format.

Candidates below the threshold stay unresolved.

When **Anime-only sync** is on, title search is skipped.

### Use Anime ID Mapping

When **Use Anime ID Mapping** is enabled, CrossWatch enriches source IDs through the local AniBridge index.

That can bridge:

* TMDb
* TVDb
* IMDb
* AniDB
* MAL
* AniList

A mapped AniList or MAL ID is preferred over title search.

### Add and update behavior

CrossWatch writes ratings through the AniList `SaveMediaListEntry` mutation.

It sends a positive `scoreRaw` value.

The same mutation handles both new ratings and updates.

Successful writes return confirmed item keys to the orchestrator.

Invalid ratings, unresolved media, and API failures return unresolved items.

### Clear behavior

Rating removal also uses `SaveMediaListEntry`.

It sends:

```json
{
  "scoreRaw": 0
}
```

This clears the rating and keeps the media list entry.

It does not change the AniList status.

### State files

This feature does not keep an AniList-specific ratings shadow file.

Orchestrator snapshots and state handle compare, plan, and confirmation.

### Code map

* `providers/sync/_mod_ANILIST.py`
* `providers/sync/anilist/_ratings.py`
* `cw_platform/anime_mapping/service.py`

### Provider capabilities

* Bidirectional: supported
* Provides stable IDs: supported
* Index semantics: `present`
* Rating updates: supported
* Rating clears: supported
* Movies: supported
* Shows: supported
* Seasons: not supported
* Episodes: not supported
* Provider-side `from_date`: not supported
  {% endtab %}
  {% endtabs %}


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_anilist/ratings.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.