# Letterboxd API
> Live Letterboxd film-diary data as an API — Letterboxd is the social network for film lovers, and this returns any member's public diary and ratings from their RSS feed. The diary endpoint lists the films a member has recently watched, each with its title, year, the member's star rating, the date watched, whether it was a rewatch, a review excerpt and the film link. The stats endpoint computes a summary of their recent watching: the number of films, their average rating, the full rating distribution, the rewatch rate and the highest-rated film. The film-social and watch-activity layer for film, social and dashboard apps. Live, no key, no cache. Distinct from TV-listings and movie-catalogue APIs — this is a Letterboxd member's own diary and ratings.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/letterboxd-api/..."
```

## Pricing
- **Free** (Free) — 13,000 calls/Mo, 5 req/s
- **Starter** ($7/Mo) — 170,000 calls/Mo, 15 req/s
- **Pro** ($21/Mo) — 820,000 calls/Mo, 40 req/s
- **Scale** ($47/Mo) — 4,100,000 calls/Mo, 100 req/s

## Endpoints

### Diary

#### `GET /v1/diary` — A member's recent film diary

**Parameters:**
- `username` (query, required, string) — Letterboxd username Example: `dave`
- `limit` (query, optional, string) — Max entries (1-50) Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/letterboxd-api/v1/diary?username=dave&limit=25"
```

**Response:**
```json
{
    "data": {
        "count": 25,
        "diary": [
            {
                "film": "Rush Hour",
                "link": "https://letterboxd.com/dave/film/rush-hour/",
                "year": 1998,
                "rating": 3.5,
                "review": "Watched on Sunday May 31, 2026.",
                "rewatch": true,
                "published": "Tue, 2 Jun 2026 02:03:37 +1200",
                "watched_date": "2026-05-31"
            },
            {
                "film": "GOAT",
                "link": "https://letterboxd.com/dave/film/goat-2026/",
                "year": 2026,
                "rating": 3.5,
                "review": "Watched on Friday May 29, 2026.",
                "rewatch": false,
                "published": "Sat, 30 May 2026 11:02:33 +1200",
                "watched_date": "2026-05-29"
            },
            {
                "film": "The Backrooms (Found Footage)",
                "link": "https://letterboxd.com/dave/film/the-backrooms-found-footage/",
                "year": 2022,
                "rating": null,
                "review": "Watched on Friday May 22, 2026.",
                "rewatch": false,
                "published": "Wed, 27 May 2026 09:57:33 +1200",
                "watched_date": "2026-05-22"
            },
            {
                "film": "PlayTime",
                "link": "https://letterboxd.com/dave/film/playtime/",
                "year": 1967,
                "rating": 3.5,
                "review":
…(truncated, see openapi.json for full schema)
```

### Stats

#### `GET /v1/stats` — Computed recent-watching stats

**Parameters:**
- `username` (query, required, string) — Letterboxd username Example: `dave`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/letterboxd-api/v1/stats?username=dave"
```

**Response:**
```json
{
    "data": {
        "latest": {
            "film": "Rush Hour",
            "rating": 3.5,
            "watched_date": "2026-05-31"
        },
        "username": "dave",
        "profile_url": "https://letterboxd.com/dave/",
        "rated_films": 28,
        "rewatch_pct": 6,
        "recent_films": 50,
        "highest_rated": {
            "film": "Resurrection",
            "year": 2025,
            "rating": 4.5
        },
        "rewatch_count": 3,
        "average_rating": 3.38,
        "rating_distribution": {
            "0.5": 0,
            "1.0": 0,
            "1.5": 0,
            "2.0": 3,
            "2.5": 4,
            "3.0": 3,
            "3.5": 6,
            "4.0": 11,
            "4.5": 1,
            "5.0": 0
        }
    },
    "meta": {
        "timestamp": "2026-06-09T03:02:00.830Z",
        "request_id": "199c1b93-6ccd-4375-b47a-367b75d43bef"
    },
    "status": "ok",
    "message": "Stats retrieved successfully",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Service metadata

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/letterboxd-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "source": "Letterboxd public member RSS (live)",
        "service": "letterboxd-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/diary": "A member's recent film diary (username=dave, limit up to 50).",
            "GET /v1/stats": "Computed recent-watching stats (username=dave): count, average rating, distribution, rewatch rate."
        },
        "description": "Live Letterboxd film-diary data from a member's public RSS: a member's recent diary (film, year, star rating, date watched, rewatch flag, review excerpt and link) and a computed summary of their recent watching (film count, average rating, rating distribution, rewatch rate, highest-rated). Live, no key. Distinct from TV and movie-catalogue APIs — this is a Letterboxd member's own diary and ratings.",
        "upstream_status": "ok"
    },
    "meta": {
        "timestamp": "2026-06-09T03:02:01.317Z",
        "request_id": "c81e686f-0b13-4193-8db8-269548f48de2"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```

### Members

#### `GET /v1/profile` — A member's lifetime profile

**Parameters:**
- `username` (query, required, string) — Letterboxd username Example: `dave`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/letterboxd-api/v1/profile?username=dave"
```

**Response:**
```json
{
    "data": {
        "username": "dave",
        "favorites": [
            {
                "year": 1963,
                "title": "High and Low"
            },
            {
                "year": 2018,
                "title": "Burning"
            },
            {
                "year": 1988,
                "title": "My Neighbor Totoro"
            },
            {
                "year": 2001,
                "title": "Mulholland Drive"
            }
        ],
        "followers": 35121,
        "following": 77,
        "profile_url": "https://letterboxd.com/dave/",
        "display_name": "Dave Vis",
        "member_since": "12/11/2011",
        "films_watched": 2567
    },
    "meta": {
        "timestamp": "2026-06-13T14:09:29.574Z",
        "request_id": "8c792ae1-5900-4f06-b811-97af9b987a88"
    },
    "status": "ok",
    "message": "Profile retrieved successfully",
    "success": true
}
```

#### `GET /v1/reviews` — A member's recent written reviews

**Parameters:**
- `username` (query, required, string) — Letterboxd username Example: `davidehrlich`
- `limit` (query, optional, string) — Max reviews (1-50) Example: `20`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/letterboxd-api/v1/reviews?username=davidehrlich&limit=20"
```

**Response:**
```json
{
    "data": {
        "count": 20,
        "reviews": [
            {
                "film": "The Furious",
                "link": "https://letterboxd.com/davidehrlich/film/the-furious/",
                "year": 2025,
                "rating": 3.5,
                "review": "There have been any number of movies about kidnappers who choose the wrong girl to abduct (e.g. “Man on Fire,” “The Searchers,” “Saving Silverman”), but none of the kidnappers in any of those movies have ever chosen wronger than the child traffickers in Kenji Tanigaki’s “The Furious,” who snatch a tradesman’s daughter off the streets and then pay for their insolence by getting their shit absolutel",
                "rewatch": false,
                "watched_date": "2026-06-12"
            },
            {
                "film": "The Death of Robin Hood",
                "link": "https://letterboxd.com/davidehrlich/film/the-death-of-robin-hood/",
                "year": 2026,
                "rating": 3,
                "review": "It would be very easy to confuse “Pig” director Michael Sarnoski’s “The Death of Robin Hood” for a gray and gritty new take on the Prince of Thieves, but that would technically be inaccurate on all counts. For starters, this movie isn’t “gray” so much as its first act looks like it was shot directly onto volcanic ash, and “gritty” feels a bit insufficient for a medieval character study that has le",
                "rewatch": false,
  
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/letterboxd-api
OpenAPI spec: https://www.oanor.com/api/letterboxd-api/openapi.json