> 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/getting-started/limitations.md).

# Limitations

CrossWatch is **not** built for very large libraries.

It is a UI-first tool with metadata enrichment, images, and safety checks. It is not a bulk-sync engine.

Huge libraries create heavy API traffic. Some providers hard-limit this. Others treat it as abuse.

This matters most when TMDb enrichment is enabled. Large watchlists drive extra metadata and image requests.

{% hint style="warning" %}
If your main goal is syncing massive datasets fast, CrossWatch is the wrong fit.
{% endhint %}

### Size guidance

These are **approximate** limits. Provider behavior matters more than hardware.

On a normal machine or NAS, overall library size is rarely the first bottleneck. The tighter limits below are about API pressure and tracker tolerance.

CrossWatch recommends these rough upper bounds for normal use:

* **Watchlist**: `~2,500`
* **History**: `~10,000`
* **Ratings**: `~10,000`

Lower counts are better. Higher counts may still work, but they are less tested and harder on providers.

{% hint style="info" %}
Prefer incremental windows for large backfills.

Ratings reads are not cached by design.
{% endhint %}

### Provider account limits

Some limits come from the provider, not CrossWatch itself.

If you have large watchlist volumes, disable TMDb enrichment first.

### Provider request limits

CrossWatch also throttles upstream APIs to reduce `429 Too Many Requests` errors.

Default request limits:

* **SIMKL**: `10` GET/sec, `1` write/sec
* **Nuvio**: `100` GET/sec, `100` write/sec
* **MDBList**: `10` GET/sec, `1` write/sec
* **PublicMetaDB**: `20` GET/sec, `3` write/sec, plus hourly rating quotas
* **Trakt**: `3.33` GET/sec, `1` write/sec

Most installs should keep these defaults.

Only tune them if you see repeated `429`, temporary `5xx`, or timeout errors.

See [Provider rate limiting](/crosswatch/advanced-and-api/rate-limiting-and-retries.md) for the short version and the full tuning reference.

### Practical advice

If your data is large:

* Start with **one pair** and **one feature**
* Use **one-way** first
* Avoid large backfills in one run
* Expect slower runs as datasets grow

If you see repeated slowdowns or unstable runs, reduce scope first.

Typical ways to do that:

* Backfill a shorter date range
* Sync one feature at a time
* Limit libraries where supported

### Related pages

<table data-view="cards"><thead><tr><th>Title</th><th data-card-target data-type="content-ref">Open</th></tr></thead><tbody><tr><td>Decide whether CrossWatch fits your setup</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/qtfUF6m4GafE3XDx2QZ8">/spaces/3rh5THg1PdhVsBt3GALo/pages/qtfUF6m4GafE3XDx2QZ8</a></td></tr><tr><td>Use safer sync defaults</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/aXxgMcv8AubC0CypFUTO">/spaces/3rh5THg1PdhVsBt3GALo/pages/aXxgMcv8AubC0CypFUTO</a></td></tr><tr><td>Tune provider pacing only when needed</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/uIdojSHyuBmDdMI0yPFg">/spaces/3rh5THg1PdhVsBt3GALo/pages/uIdojSHyuBmDdMI0yPFg</a></td></tr><tr><td>Review runtime knobs</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/KaMtaAGBjgDvoh2g6LxO">/spaces/3rh5THg1PdhVsBt3GALo/pages/KaMtaAGBjgDvoh2g6LxO</a></td></tr></tbody></table>


---

# 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/getting-started/limitations.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.