> 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/providers/synchronization/adapter-simkl.md).

# Adapter: SIMKL

SIMKL adapter lets CrossWatch sync with SIMKL. It supports watchlist, ratings, and history, including anime.

{% hint style="info" %}
Connect SIMKL first. Use: [SIMKL (Authentication provider)](/crosswatch/providers/authentication/auth-trackers/auth-simkl.md).
{% endhint %}

{% hint style="info" %}
CrossWatch rate-limits SIMKL calls to reduce `429 Too Many Requests`.

Default: `10` GET/sec, `1` write/sec.

Tuning: [Provider rate limiting](/crosswatch/provider-rate-limiting.md)
{% endhint %}

{% hint style="warning" %}
Be kind to SIMKL’s API. Don’t schedule SIMKL runs more often than **every 12 hours**. Daily is better.
{% endhint %}

### What it supports

* Direction: source or target in a pair (one-way or two-way)
* Features:
  * **Watchlist** → SIMKL **PTW** (“Plan To Watch”)
  * **Ratings** (1–10)
  * **History** (watched movies + watched episodes)
  * **Playlists** (not supported)
* Delta sync: uses SIMKL **activities** and **watermarks** to avoid full downloads
* IDs: works best with `simkl`, `imdb`, `tmdb`, `tvdb`
  * Anime can also use `mal`, `anilist`, `kitsu`, `anidb` when available

{% hint style="warning" %}
SIMKL PTW is a **status list**, not a “save for later” watchlist. Items can leave PTW due to SIMKL status changes.
{% endhint %}

### Watchlist behavior (PTW)

* Read: incremental list reads per bucket (`movies`, `shows`, `anime`)
* Write: add/remove items to PTW

{% hint style="info" %}
SIMKL writes mainly use movies/shows payloads. CrossWatch still reads the anime bucket for indexing.
{% endhint %}

### Ratings behavior

* Read: incremental ratings feed (movies/shows/anime)
* Write: upsert and remove ratings

{% hint style="info" %}
Writing anime ratings depends on how the source provider represents anime.
{% endhint %}

### History behavior

* Read: incremental watched state for movies/shows/anime
* Write: mark watched or unwatch

Anime writes can add `use_tvdb_anime_seasons=true` to help season mapping.

### Settings (advanced)

<details>

<summary>Headers sent to SIMKL</summary>

* `simkl-api-key: <client id>`
* `Authorization: Bearer <access token>`
* `User-Agent: CrossWatch/3.x (SIMKL)` (override with `CW_UA`)
* `Accept: application/json`
* `Content-Type: application/json`

</details>

<details>

<summary>Delta syncing: date_from and watermarks</summary>

SIMKL uses per-feature watermarks stored under:

* `/config/.cw_state/simkl.watermarks.&lt;pair&gt;.json`

For each feature, CrossWatch picks `date_from` in this order:

1. Stored watermark
2. `SIMKL_<FEATURE>_DATE_FROM`
3. `SIMKL_DATE_FROM`
4. `simkl.date_from`
5. `1970-01-01T00:00:00Z`

Watermarks only move forward.

</details>

<details>

<summary>Health check</summary>

SIMKL health is probed with:

* `POST /sync/activities`

It also acts as an “activities gate” to skip work when nothing changed.

</details>

<details>

<summary>State files (per pair)</summary>

All state lives in `/config/.cw_state/`:

* `simkl.watermarks.<pair>.json`
* `simkl.watchlist.shadow.<pair>.json`
* `simkl.watchlist.unresolved.<pair>.json`
* `simkl.ratings.shadow.<pair>.json`
* `simkl_ratings.unresolved.<pair>.json`
* `simkl.history.shadow.<pair>.json`
* `simkl_history.unresolved.<pair>.json`
* `simkl.show.map.<pair>.json`

Deleting these forces rebuilds and usually increases API calls next run.

</details>


---

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

```
GET https://wiki.crosswatch.app/crosswatch/providers/synchronization/adapter-simkl.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.