> 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/connections/trackers/simkl.md).

# SIMKL

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

<figure><img src="https://565675962-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3rh5THg1PdhVsBt3GALo%2Fuploads%2Fyba9019B5bvI14TLWm9F%2Fimage.png?alt=media&amp;token=1d0f1862-dfea-4151-b6b9-2aecad11bb91" alt=""><figcaption></figcaption></figure>

Connect SIMKL to synchronize supported activity and configure real-time scrobbling.

{% hint style="info" %}
SIMKL is also used for scrobbling (Watcher/Webhooks) when configured.
{% endhint %}

### What CrossWatch can sync

**Read** brings data into CrossWatch; **Write** sends changes to this provider.

| Feature    | Read | Write | Notes                                                                                                                                              |
| ---------- | ---- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Watchlist  | Yes  | Yes   | Movies, shows and anime in Plan to Watch.                                                                                                          |
| History    | Yes  | Yes   | Movies and episodes. Optional rewatch support requires Pro or VIP.                                                                                 |
| Ratings    | Yes  | Yes   | Movies and shows, including anime.                                                                                                                 |
| Progress   | Yes  | Yes   | Resume positions for movies and episodes.                                                                                                          |
| Playlists  | Yes  | Yes   | Status lists and owned regular custom lists are writable. Custom lists need PRO/VIP. Status-list removals also remove library entries and ratings. |
| Collection | No   | No    | Unsupported.                                                                                                                                       |

**Live scrobbling:** Scrobble destination; cannot be a Watcher source.

See the [synchronization guide](https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/simkl.md) for matching rules and feature restrictions.

### Connect SIMKL

#### Connect with PIN

PIN is the recommended method. It does not need a SIMKL developer app.

1. Open **CrossWatch**.
2. Go to **Settings** → **Connections** → **Trackers** → **SIMKL**.
3. Select **PIN**.
4. Click **Connect SIMKL**.
5. CrossWatch shows a short authorization code.
6. Enter the code at [SIMKL PIN](https://simkl.com/pin).
7. Approve the connection.
8. Return to CrossWatch.

CrossWatch checks the authorization status automatically. It then shows **Connected using PIN**.

{% hint style="info" %}
CrossWatch opens the SIMKL PIN page in a new browser tab. If blocked, open [SIMKL PIN](https://simkl.com/pin) manually.
{% endhint %}

If the code expires, click **Restart** and repeat the authorization.

#### Migrate from OAuth

OAuth will be removed in a future release. Migrate to the PIN flow as soon as possible.

1. Open **CrossWatch**.
2. Go to **Settings** → **Connections** → **Trackers** → **SIMKL**.
3. Select **PIN** and complete the [PIN authorization](#connect-with-pin).

{% hint style="warning" %}
Do not create new SIMKL OAuth applications. Use PIN for all new connections.
{% endhint %}

### Custom lists

Use [Playlists](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/playlists.md#simkl) to create or sync your own regular custom lists. This requires **PRO or VIP** and authorization that permits custom-list changes. New custom lists default to **Public**; choose **Private** or **Unlisted** when needed. If a write asks for a reconnect, reconnect this SIMKL account before retrying.

### Limitations

* Watchlist: stable up to \~2,500 items total (max 10,000)
* History (plays): stable up to \~10,000 play events total.
* Ratings: stable up to \~10,000 ratings total.

Prefer incremental windows for big backfills.

### Troubleshooting

* If the PIN page does not open, allow popups for CrossWatch.
* If the PIN expires, click **Restart** to get a new code.
* If you run sync very often, SIMKL may throttle you. Daily is usually enough.
* If you see `429 Too Many Requests`, tune provider throttling.\
  Guide: [Provider rate limiting](https://wiki.crosswatch.app/crosswatch/advanced-and-api/rate-limiting-and-retries.md).
  {% endtab %}

{% tab title="Power users" %}

## Power users

### Config keys

Stored under:

* `simkl.*`

Common keys:

* `simkl.client_id`, `simkl.client_secret`
* `simkl.access_token`

### Related docs

* Sync module: [SIMKL module](https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/simkl.md)
* Adapter: [Adapter: SIMKL](https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/simkl.md)
  {% 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 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/connections/trackers/simkl.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.
