---
title: Watchlist
description: Read, add to, and remove from an account's watchlist.
section: Your data
order: 4
---

# Watchlist

Read, add to, and remove from the signed-in user's watchlist.

> [!REQUIRED]
> `GET /v3/sync/watchlist` needs the `read` scope. `POST` and `DELETE` need `write`. See [Authentication](/dev/authentication).

## Reading the watchlist

:::tabs
```bash
curl -H "Authorization: Bearer $TOKEN" \
  "https://flicklist.tv/api/v3/sync/watchlist"
```
```javascript
const res = await fetch('https://flicklist.tv/api/v3/sync/watchlist', {
  headers: { Authorization: `Bearer ${token}` }
});
const watchlist = await res.json();
```
```python
import requests
r = requests.get(
    "https://flicklist.tv/api/v3/sync/watchlist",
    headers={"Authorization": f"Bearer {token}"},
)
watchlist = r.json()
```
:::

```json
[
  {
    "status": "plan_to_watch",
    "progress": 0.0,
    "added_at": "2026-05-14T02:10:33.000Z",
    "started_at": null,
    "completed_at": null,
    "title": "Dune: Part Two",
    "year": 2024,
    "media_type": "movie",
    "ids": { "fldb": "flm_2f81c6b3", "slug": "dune-part-two", "tmdb": 693134, "imdb": "tt15239678", "tvdb": null, "anilist": null }
  }
]
```

`progress` here is a 0.0-1.0 fraction, a different scale than the 0-100 `progress` on [Playback progress](/dev/sync/playback).

## Adding to the watchlist

`POST /v3/sync/watchlist` adds up to 1000 items as `plan_to_watch`. Build each item's `ids` block per [The ids object](/dev/ids).

```json
{ "items": [ { "ids": { "tmdb": 693134 }, "media_type": "movie" } ] }
```

Upsert semantics apply: an item already on the watchlist still counts as `added`, since the call still succeeded idempotently.

```json
{ "added": 1, "not_found": [] }
```

## Removing from the watchlist

`DELETE /v3/sync/watchlist` takes the same body shape and removes the matching entries.

```json
{ "removed": 1, "not_found": [] }
```

> [!WARNING]
> Batches are capped at 1000 items per request. An item whose `ids` don't resolve lands in `not_found` rather than failing the whole batch.