> ## Documentation Index
> Fetch the complete documentation index at: https://api.simkl.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Watchlist statuses

> The watchlist statuses Simkl uses — and the per-type rules. Movies don't have watching or hold; TV and anime do.

Every item in a user's library lives in exactly one status bucket. **The set of valid statuses is not the same across types** — movies are restricted to three statuses, while TV shows and anime get all five.

## Per-type matrix

| Status        | Movies |  TV | Anime | Display name  |
| ------------- | :----: | :-: | :---: | ------------- |
| `watching`    |    —   |  ✓  |   ✓   | Watching      |
| `plantowatch` |    ✓   |  ✓  |   ✓   | Plan to Watch |
| `hold`        |    —   |  ✓  |   ✓   | On Hold       |
| `dropped`     |    ✓   |  ✓  |   ✓   | Dropped       |
| `completed`   |    ✓   |  ✓  |   ✓   | Completed     |

<Note>
  **TV and anime accept the same five statuses.** The difference that matters in code is **movies vs everything else** — movies skip `watching` and `hold`.
</Note>

<Info>
  **These are Simkl's built-in *Watchlist* statuses, not user-defined Custom Lists.** Custom Lists — the user-curated, named collections you see at [simkl.com/lists/](https://simkl.com/lists/) — are a separate concept and **not yet available via the API**. See the [Custom Lists guide](/guides/custom-lists) for status and what to use in the meantime.
</Info>

## Why movies are different

Movies are single-session content — there's no progress to "pause" the way a 10-episode TV season has. Simkl reflects this in the API in four concrete ways:

**1. [`POST /sync/add-to-list`](/api-reference/simkl/add-to-list) silently upgrades `watching` to `completed` for movies.** Posting `to: "watching"` for a movie is not an error — the API quietly converts it to `completed` and records the watch. Posting `to: "hold"` for a movie has no defined behavior; don't rely on it.

**2. [`GET /sync/all-items/movies/watching`](/api-reference/simkl/get-all-items) and `/movies/hold` return empty.** The URL is accepted (won't 404), but no movie can be in those states, so the response is always empty. Don't paginate these endpoints — there's nothing to fetch.

**3. [`GET /sync/activities`](/api-reference/simkl/get-activities) strips `watching` and `hold` from the `movies` block.** Build your client around this shape — don't expect `movies.watching` or `movies.hold` keys.

**4. [`POST /users/USER_ID/stats`](/api-reference/simkl/get-user-stats) skips `watching` and `hold` for movies.** Stats responses don't include those buckets for movies. Plan-to-watch movies show up; "in progress" / "on hold" never do.

## Where statuses appear

<CardGroup cols={2}>
  <Card title="Read a watchlist" icon="list" href="/api-reference/simkl/get-all-items">
    `GET /sync/all-items/:type/:status` — read items in one bucket. Use `all` for everything.
  </Card>

  <Card title="Move an item" icon="arrows-left-right" href="/api-reference/simkl/add-to-list">
    `POST /sync/add-to-list` — set `to` to one of the five statuses to move the item between buckets.
  </Card>

  <Card title="Remove from history" icon="circle-minus" href="/api-reference/simkl/remove-from-history">
    `POST /sync/history/remove` — the canonical way to remove a watched item from the user's history.
  </Card>

  <Card title="Detect changes" icon="rotate" href="/api-reference/simkl/get-activities">
    `GET /sync/activities` returns timestamps per status bucket — only re-sync the watchlists whose timestamp moved.
  </Card>
</CardGroup>

<Note>
  **To remove an item, use [`POST /sync/history/remove`](/api-reference/simkl/remove-from-history)** — not `POST /sync/add-to-list` with `to: "remove"`. The history endpoint is the canonical removal path; it cleanly un-marks the item watched and clears it from the user's library.

  **Removing also clears the rating.** If the user had rated the item, Simkl wipes the rating along with the watch record — you'll see both `removed_from_list` and `rated_at` move on the next `/sync/activities` call.
</Note>

## Status vs. progress

`status` says **where in the library** an item lives. The `watched_episodes_count`, `total_episodes_count`, and `last_watched_at` fields say **how far the user is**.

A TV show in `status: watching` with 3 of 10 episodes watched is normal. A show in `status: completed` should always have `watched_episodes_count` equal to `total_episodes_count`. The two evolve together but they're separate concepts.

For movies, `status: completed` simply means the user marked the movie watched — there's no episode count to track.

## Quick examples

```bash Read all "watching" anime theme={"theme":{"light":"github-light","dark":"vesper"}}
curl "https://api.simkl.com/sync/all-items/anime/watching?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" \
  -H "User-Agent: my-app-name/1.0" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

```bash Mark a movie completed theme={"theme":{"light":"github-light","dark":"vesper"}}
curl -X POST "https://api.simkl.com/sync/add-to-list?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" \
  -H "User-Agent: my-app-name/1.0" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "completed", "movies": [{ "ids": { "simkl": 53536 } }] }'
```

```bash Drop a TV show theme={"theme":{"light":"github-light","dark":"vesper"}}
curl -X POST "https://api.simkl.com/sync/add-to-list?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" \
  -H "User-Agent: my-app-name/1.0" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "dropped", "shows": [{ "ids": { "tmdb": "1399" } }] }'
```

```bash Pause an anime ("on hold") theme={"theme":{"light":"github-light","dark":"vesper"}}
curl -X POST "https://api.simkl.com/sync/add-to-list?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" \
  -H "User-Agent: my-app-name/1.0" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "hold", "anime": [{ "ids": { "mal": "11757" } }] }'
```

```bash Remove a show from the user's library theme={"theme":{"light":"github-light","dark":"vesper"}}
curl -X POST "https://api.simkl.com/sync/history/remove?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" \
  -H "User-Agent: my-app-name/1.0" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "shows": [{ "ids": { "tmdb": "1399" } }] }'
```

## Related

<CardGroup cols={3}>
  <Card title="Sync guide" icon="arrows-rotate" href="/guides/sync">
    Read and write watchlists, history, and ratings.
  </Card>

  <Card title="Mark as watched" icon="circle-check" href="/guides/mark-as-watched">
    `POST /sync/history` recipes that don't go through scrobble.
  </Card>

  <Card title="Standard media objects" icon="film" href="/conventions/standard-media-objects">
    The shared shape every watchlist endpoint returns.
  </Card>
</CardGroup>