> 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="/files/6RmTnfd9Qu7MNKkUwOhq" alt=""><figcaption></figcaption></figure>

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

### 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** → **Authentication** → **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.

#### Connect with OAuth

OAuth is optional. Use it with your own SIMKL developer app.

1. Open [SIMKL developer settings](https://simkl.com/settings/developer/).
2. Click **Add** → **Add a new App**.
3. Set **Name** and **Description** to `CrossWatch`.
4. Set **Redirect URI** to the callback URL shown by CrossWatch. For example: `http://<your-server-ip>:8787/callback`.
5. Click **Save Changes**.
6. Copy the **Client ID** and **Client Secret** into CrossWatch.
7. Select **OAuth**, then click **Connect SIMKL**.
8. Approve the connection in SIMKL.

{% hint style="warning" %}
If you change the host, port, or protocol, update the OAuth **Redirect URI**.

See [HTTPS/TLS](/crosswatch/advanced-and-api/https-and-tls.md).
{% endhint %}

### 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 OAuth fails, verify that the redirect URI matches exactly.
* 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](/crosswatch/advanced-and-api/rate-limiting-and-retries.md).
  {% endtab %}

{% tab title="Power users" %}

### Config keys

Stored under:

* `simkl.*`

Common keys:

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

### Related docs

* Sync module: [SIMKL module](broken://spaces/3rh5THg1PdhVsBt3GALo/pages/6d90d0a66a006bf6af4d6a75e6db99e974447856)
* Adapter: [Adapter: SIMKL](/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 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/crosswatch/settings/connections/trackers/simkl.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.