> 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/kitsu.md). # Kitsu Sync anime watchlists, ratings, and watched history with Kitsu. Sync anime watchlists, ratings, and watched history with Kitsu. Kitsu can be a one-way source or destination. It can also participate in compatible two-way syncs. {% hint style="warning" %} Kitsu is an experimental, anime-only provider. Start with a one-way pair. 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 title ratings. * **History:** Read and update watched anime movies and episode progress, including supported removals. * **Connection profiles:** Select the Kitsu account used by the pair. **Anime-only sync** is always enabled and locked for Kitsu watchlist, ratings, and history pairs. Non-anime items are excluded. Manga, playback position, and resume syncing are unsupported. ### Prerequisite: connect Kitsu Connect your account under **Settings → Connections → Kitsu**. Save the connection before creating a sync pair. Guide: [Kitsu](/crosswatch/settings/connections/trackers/kitsu.md). ### How matching works Kitsu uses Kitsu anime IDs. Other providers may identify the same title with IMDb, TMDb, TVDB, AniList, or MyAnimeList IDs. CrossWatch uses **Anime ID Mapping** to bridge those IDs and translate episode numbering. * An existing Kitsu ID can identify a title directly. * Anime ID Mapping can resolve other supported IDs to a Kitsu title. * Episode history needs mapping to translate seasons and episode numbers to Kitsu's episode count. It also maps them back when Kitsu is the source. * Custom mappings can correct title matches and episode ranges. * Kitsu does not fall back to title searches. Items without usable matches are skipped or unresolved. {% hint style="info" %} Enable global **Anime ID Mapping** before syncing episode history or titles across providers. Check custom mappings when services split a series into seasons or cours differently. Guide: [Anime ID Mapping](/crosswatch/settings/connections/metadata/anime-id-mapping.md). {% endhint %} ### Watchlist Kitsu's watchlist contains titles marked **Plan to Watch**. Watching, completed, on-hold, and dropped titles are outside this watchlist. Adding a title creates a Plan to Watch entry. CrossWatch does not move existing titles from another watch status. It reports that the existing status was preserved. Removing a Plan to Watch title deletes an otherwise empty library entry. If the entry retains progress, a rating, notes, or other library information, CrossWatch moves it to **On Hold** instead. ### Ratings Ratings apply to anime movies and series, not individual seasons or episodes. CrossWatch converts Kitsu ratings to its 1–10 scale. Half-point Kitsu ratings round to the nearest whole point. Updating or removing a rating preserves the existing watch status and episode progress. Rating a title outside the Kitsu library creates a **Watching** entry. ### History to Kitsu Kitsu stores one watched episode count per anime title. It does not store a separate event for every episode. * Episodes map to the appropriate Kitsu title and episode number. * Adding history advances progress to the highest selected episode. It never lowers existing progress. * Selecting episode 5 marks episodes 1 through 5 watched in Kitsu. * Reaching a finished series' final episode marks the title **Completed**. * Anime movies are marked **Completed**. CrossWatch groups episode changes by Kitsu title within each write batch. It updates each title's progress together. A title spanning several batches may still need more than one update. #### Use source watch status For **SIMKL → Kitsu** history pairs, enable **Use source watch status**. It carries SIMKL's dropped or on-hold status when writing episode progress. Completed progress takes precedence. This option accompanies history writes. A status change alone creates no separate history change. #### Removing history Enable **Remove** in the pair's History settings to allow supported removals. Kitsu 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. Removing all watched episodes, or removing a movie's watched state, resets progress to zero. It moves the title to **On Hold**. Ratings and notes are preserved. A completed title with an unknown episode total may need corrected mapping or metadata before removal. ### History from Kitsu CrossWatch expands Kitsu episode progress into watched episodes. It maps them to the destination provider. Completed movies are exported as watched movies. These are derived watched states, not individual playback records. Kitsu library timestamps can be shared across every episode in a title. They do not provide each episode's original watch date. {% hint style="info" %} **Rewatches** and **Specials (Season 0)** are unsupported by Kitsu history sync. The episode count cannot represent gaps or repeat viewings. {% endhint %} ### Snapshot model Kitsu sync reads the current anime library through paginated API requests. It builds a snapshot for each enabled feature. It does not use an incremental change feed. An Interactive Sync review and its pre-apply recheck can both read the library. Watchlist and ratings writes reuse library lookups within each batch. History writes group episodes by title. Proposed episode changes do not equal API requests. ### Rate limits and token lifecycle Kitsu requests use CrossWatch's shared HTTP handling. Rate-limit responses can delay a sync. Interactive Sync shows request activity. Access tokens refresh automatically with the saved refresh token. If Kitsu rejects it, reconnect the selected account under **Settings → Connections → Kitsu** and save it again. CrossWatch does not retain your Kitsu password. ### Best practices * Enable Anime ID Mapping. Check a few known titles before a large sync. * Start one-way. Enable two-way sync only after validating mappings and results. * Use Interactive Sync to review unresolved matches and proposed removals. * Remember that adding a later episode marks preceding episodes watched in Kitsu. * Use custom mappings for missing titles, split seasons, or incorrect episode numbering. --- # 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 following URL with the `ask` and `goal` query parameters: ``` GET https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/kitsu.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 `build a script that syncs our docs to a CMS` 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.