# List your Lists

> Lists the user's own Lists, then the Public Lists they subscribe to.

`GET /account/lists` on `https://api.mediux.io`

Each row is the public List summary plus `relation` (`owned` or `subscribed`) and `isPublic`, so private Lists are included for their owner. Pages default to 50 and hold at most 100. Pass `meta.nextCursor` as `after` to continue.

## Authorization

OAuth 2 bearer token in the `Authorization` header. Required permission: `lists:read`.

## Parameters

- `after` (query, string): The `meta.nextCursor` from the previous page.
- `limit` (query, string): Page size, 1 to 100. Defaults to 50.

## Responses

### 200

A page of Lists.

- `data` (array of object, required)
  - `kind` (string, required): One of "assetList", "mediaList", "gameList".
  - `id` (string (uuid), required)
  - `name` (string, required)
  - `description` (string, nullable, required)
  - `owner` (object, required)
    - `id` (string (uuid), required)
    - `username` (string, required)
  - `relation` (string, required): One of "owned", "subscribed".
  - `isPublic` (boolean, required)
  - `itemCount` (integer, required)
  - `subscriberCount` (integer, required)
  - `createdAt` (string, required): ISO 8601 UTC instant with milliseconds, such as `2026-11-14T15:03:02.000Z`.
  - `updatedAt` (string, required): ISO 8601 UTC instant with milliseconds, such as `2026-11-14T15:03:02.000Z`.
- `meta` (object, required)
  - `limit` (integer, required)
  - `nextCursor` (string, nullable, required)

### 400

The request is malformed or failed validation. Inspect `error.code` and `error.issues`.

### 401

The access token is missing (`auth.required`), or invalid, expired or revoked (`auth.invalidToken`).

### 403

The token lacks the required App Permission (`auth.insufficientScope`, with `details.required`), or the account or connection may not do this (`auth.forbidden`).

### 429

Too many requests. Wait the `Retry-After` seconds before trying again.

### 503

Temporarily unavailable. Check the outcome before retrying a write.

## Example response (200)

```json
{
  "data": [
    {
      "kind": "mediaList",
      "id": "8a7b7fea-4908-4b1a-af26-1ffc8c4fea49",
      "name": "API sample Library",
      "description": "Created through the API for the Bruno examples",
      "owner": {
        "id": "b6c53317-87e3-4f0a-ab9b-bc3c272d4f06",
        "username": "ApiSamples"
      },
      "relation": "owned",
      "isPublic": false,
      "itemCount": 2,
      "subscriberCount": 0,
      "createdAt": "2026-11-19T11:52:41.808Z",
      "updatedAt": "2026-11-19T11:52:42.156Z"
    },
    {
      "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"
      },
      "relation": "subscribed",
      "isPublic": true,
      "itemCount": 5,
      "subscriberCount": 1,
      "createdAt": "2026-10-28T07:02:47.806Z",
      "updatedAt": "2026-10-28T07:03:11.678Z"
    }
  ],
  "meta": {
    "limit": 50,
    "nextCursor": null
  }
}
```
