---
title: Ratings
description: Read, add, and remove ratings for an account.
section: Your data
order: 5
---

# Ratings

Read, add, and remove ratings for the signed-in user, on a 0.5 to 10.0 scale.

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

## Reading ratings

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

```json
[
  {
    "rating": 9.0,
    "rated_at": "2026-05-14T02:10:33.000Z",
    "season_number": null,
    "episode_number": null,
    "title": "The Shawshank Redemption",
    "year": 1994,
    "media_type": "movie",
    "ids": { "fldb": "flm_7d3a95e0", "slug": "the-shawshank-redemption", "tmdb": 278, "imdb": "tt0111161", "tvdb": null, "anilist": null }
  }
]
```

## Adding ratings

`POST /v3/sync/ratings` rates up to 1000 items in one batch. Build each item's `ids` block per [The ids object](/dev/ids).

```json
{ "items": [ { "ids": { "tmdb": 278 }, "media_type": "movie", "rating": 9.0 } ] }
```

Every `rating` must fall between 0.5 and 10 in half-point increments, and any item that sets `episode` must also set `season`. Unlike the other bulk write endpoints, this validation runs over the whole batch before anything is written: either violation fails the entire request with a 400 instead of applying the valid items and skipping the rest. Per-item `ids` resolution failures still land in `not_found` as usual.

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

## Removing ratings

`DELETE /v3/sync/ratings` takes a bare media identity, no `rating` field, and clears the matching rating.

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

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

> [!WARNING]
> Batches are capped at 1000 items per request.