> 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/others/tracearr.md).

# Tracearr

Tracearr adapter notes for importing watch history into CW.

Tracearr is a **read-only history importer**. It reads play history from Tracearr's public API and normalizes it for CW. Tracearr can monitor Plex, Jellyfin, and Emby.

{% hint style="warning" %}
**Experimental:** Use Interactive Sync and check the results. One-way syncing is strongly recommended.
{% endhint %}

{% hint style="info" %}
Connect Tracearr first. Use: [Tracearr](/crosswatch/settings/connections/others/tracearr.md).
{% endhint %}

### What it supports

* Direction: **source-only**
* History import for movies and episodes
* Rewatches: each play can remain a separate watch
* Writes: **not supported**

It does not support watchlists, ratings, progress, playlists, music, live TV, or photos. It cannot sync back to Tracearr or its Plex, Jellyfin, or Emby servers.

### How indexing works

1. Retrieves pages from `/history` with 100 plays per page. It stops at the next-cursor boundary or safety limit.
2. Keeps only `media_type` values of `movie` or `episode`.
3. Keeps only plays Tracearr marks as watched. Tracearr uses its own thresholds, which default to 85%.
4. Uses the available TMDb, IMDb, and TVDb IDs for movies.
5. For episodes, retrieves show IDs from `/media/{show_media_id}` once per show and caches them.
6. For unlinked plays, borrows show IDs from a play with the same show title and server. Ambiguous titles are skipped.
7. Uses external IDs as primary keys. The source-server item key (`plex`, `jellyfin`, or `emby`) is the fallback.

Without rewatches, history is a de-duplicated snapshot. The newest play wins for each canonical key. With rewatches enabled on the pair, every play remains a separate entry.

### Output shape

Movies and episodes include an `ids` object with available IMDb, TMDb, and TVDb IDs. They also include the source-server item key. Episodes use the **show's** IDs, never the episode's own IDs.

```json
{
  "type": "episode",
  "ids": {
    "tmdb": "103516",
    "imdb": "tt12327578",
    "tvdb": "382389",
    "plex": "43892"
  },
  "show_ids": {
    "tmdb": "103516",
    "imdb": "tt12327578",
    "tvdb": "382389"
  },
  "series_title": "Star Trek: Strange New Worlds",
  "season": 4,
  "episode": 9,
  "watched_at": "2026-09-19T08:57:43Z"
}
```

### Limits

* Plays unlinked to a library item can lack IDs. CW skips them and reports `skipped_no_ids`.
* Tracearr allows about 240 API requests per minute per key. Large first syncs can take several minutes.

### Recommended workflows

{% stepper %}
{% step %}

### Import into CW

Run a pair: **Tracearr → CW** with **History** enabled. Then use CW as the source for downstream services.
{% endstep %}

{% step %}

### Import into an Editor dataset

Use an Editor dataset to clean history, fix matches, and correct metadata before syncing elsewhere.
{% endstep %}
{% endstepper %}

### Endpoints used

All requests use `Authorization: Bearer trr_pub_...`.

* `GET /api/v2/public/history` — history pages with cursor paging. Supports optional `user_id` and `server_id`.
* `GET /api/v2/public/media/{show_media_id}` — show IDs for episodes.
* `GET /api/v2/public/users` — connection check and user picker.


---

# 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/synchronization/others/tracearr.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.