# Retrieve a List

> Returns a Public List: its header and, for a Media or Game List, every title with its top-level poster; an Asset List returns its images.

`GET /lists/{id}` on `https://api.mediux.io`

`kind` is `assetList`, `mediaList` or `gameList`. A Media or Game List holds up to 500 titles, with or without artwork (`titles[]`: `entity`, `position`, `poster`, `choiceCount`, `updatedAt`); a title's Season, Episode and other choices are on `/lists/{id}/titles/{family}/{entity}`. An Asset List returns its images (at most 1,000 and, after one Set add, at most 3,499) as full Asset objects in `items`, in List order. `owner` is `{id, username}`; `subscriberCount` is embedded and refreshes hourly, and Like counts are not served. Private, unknown or deleted Lists return `404` (stored at the edge for 24 hours, never by the browser). Responses are stored but revalidated with the `ETag`.

## Parameters

- `id` (path, string, required): The List's ID (a lowercase UUID).

## Responses

### 200

The List.

- `data` (object, required)

### 304

Not modified. The `If-None-Match` validator still matches; no body.

### 400

The path is not a valid route, or the request carried a query string or body.

### 404

The resource does not exist or is not public.

### 405

Only `GET`, `HEAD` and `OPTIONS` are supported.

### 429

Too many cache misses from this address. Retry after the `Retry-After` delay.

### 503

Temporarily unavailable. Retry after the `Retry-After` delay.

## Example response (200)

```json
{
  "data": {
    "kind": "mediaList",
    "id": "3bbc9c83-2ac1-4cdb-85db-e3634f32fb1e",
    "name": "Sample Media Library",
    "description": "Screenshot sample: shows, movies and collections",
    "owner": {
      "id": "2bd3576d-22be-453a-a780-ae27ba44401e",
      "username": "Koltom"
    },
    "itemCount": 5,
    "subscriberCount": 0,
    "createdAt": "2026-10-28T07:02:47.806Z",
    "updatedAt": "2026-10-28T07:03:11.678Z",
    "titles": [
      {
        "entity": {
          "id": 456,
          "title": "The Simpsons",
          "year": 1989,
          "kind": "show"
        },
        "position": 1,
        "poster": null,
        "choiceCount": 0,
        "updatedAt": "2026-10-28T07:03:11.678Z"
      },
      {
        "entity": {
          "id": 84,
          "title": "Indiana Jones Collection",
          "year": 1981,
          "kind": "collection"
        },
        "position": 2,
        "poster": null,
        "choiceCount": 0,
        "updatedAt": "2026-10-28T07:03:11.678Z"
      },
      {
        "entity": {
          "id": 614696,
          "title": "#Alive",
          "year": 2020,
          "kind": "movie"
        },
        "position": 3,
        "poster": null,
        "choiceCount": 0,
        "updatedAt": "2026-10-28T07:03:11.678Z"
      },
      {
        "entity": {
          "id": 63,
          "title": "Twelve Monkeys",
          "year": 1995,
          "kind": "movie"
        },
        "position": 4,
        "poster": null,
        "choiceCount": 0,
        "updatedAt": "2026-10-28T07:03:11.678Z"
      },
      {
        "entity": {
          "id": 97546,
          "title": "Ted Lasso",
          "year": 2020,
          "kind": "show"
        },
        "position": 5,
        "poster": null,
        "choiceCount": 0,
        "updatedAt": "2026-10-28T07:03:11.678Z"
      }
    ]
  }
}
```
