> ## Documentation Index
> Fetch the complete documentation index at: https://docs.publica.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Get List Items

Read the publications a list of the target user holds. Any list of the store can be read, private ones included.

This endpoint requires an administrator token. See the [Lists API Overview](./lists-v3-overview.md) for authentication.

---

## Item payload

| Field        | Type           | Description                                                                                                                              |
| ------------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `content_id` | string         | publica.la id of the publication                                                                                                         |
| `isbn`       | string or null | Primary identifier of the publication, `null` when it has none                                                                           |
| `title`      | string         | Title of the publication                                                                                                                 |
| `reader_url` | string         | URL that opens the publication in the reader                                                                                             |
| `added_at`   | string or null | ISO 8601 timestamp of when the publication was added to the list, `null` for publications added before the platform started recording it |

Items come back in a stable order, the same order on every request, which is what lets a cursor page through a list without repeating or skipping an item. That order is not chronological.

:::info What is left out
Only publications are returned. Subscription plans a user added to the list from the storefront are omitted, and so are publications that are no longer available in your store.
:::

---

## Get the items of a list {#by-list}

### Endpoint

```
GET /api/v3/lists/{list}/items
```

### Path parameters

| Parameter | Type   | Description                                                                                                                     |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `list`    | string | The `favorites` slug, or the `id` of one of the user's lists. See [Addressing a list](./lists-v3-overview.md#addressing-a-list) |

### Query parameters

| Parameter          | Type    | Default | Description                                                        |
| ------------------ | ------- | ------- | ------------------------------------------------------------------ |
| `user_external_id` | string  | -       | Your identifier for the user. Required unless `user_email` is sent |
| `user_email`       | string  | -       | Email of the user. Required unless `user_external_id` is sent      |
| `per_page`         | integer | `100`   | Items per page, between `1` and `500`                              |
| `cursor`           | string  | -       | Cursor token, taken from `links.next`                              |

Exactly one of `user_external_id` and `user_email` must be sent.

### Response

**Success (200):**

```json
{
  "data": [
    {
      "content_id": "468166",
      "isbn": "9781234567890",
      "title": "Conversations with Donald Hall",
      "reader_url": "https://yourstore.publica.la/reader/conversations-with-donald-hall",
      "added_at": "2026-08-27T12:00:00.000000Z"
    }
  ],
  "links": {
    "next": null,
    "prev": null
  },
  "meta": {
    "has_more": false
  }
}
```

### Examples

#### The favorites of a user

```bash
curl -X GET "https://yourstore.publica.la/api/v3/lists/favorites/items?user_external_id=student-1042" \
  -H "X-User-Token: your-api-token" \
  -H "Accept: application/json"
```

#### Identify the user by email

```bash
curl -X GET "https://yourstore.publica.la/api/v3/lists/favorites/items?user_email=student@example.com" \
  -H "X-User-Token: your-api-token" \
  -H "Accept: application/json"
```

#### Next page

```bash
curl -X GET "https://yourstore.publica.la/api/v3/lists/favorites/items?user_external_id=student-1042&per_page=100&cursor=eyJwcm9kdWN0X2lkIjo0Njgx..." \
  -H "X-User-Token: your-api-token" \
  -H "Accept: application/json"
```

#### Any other list, by id

```bash
curl -X GET "https://yourstore.publica.la/api/v3/lists/9f2d4b1e-6c3a-4f58-9b77-1d0a2e5c8b34/items?user_external_id=student-1042" \
  -H "X-User-Token: your-api-token" \
  -H "Accept: application/json"
```

### Errors

| Status | Message                                            | Cause                                                                                                      |
| ------ | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `401`  | `Unauthenticated.`                                 | Missing or invalid `X-User-Token`                                                                          |
| `403`  | `This store cannot access the integrations API.`   | The store does not have the integrations API enabled                                                       |
| `403`  | `This token cannot operate on other users' lists.` | The token does not belong to a store administrator                                                         |
| `404`  | `The specified user does not exist in this store.` | No user matches the identifier sent                                                                        |
| `404`  | `Not found`                                        | Not a list of the target user, an unknown slug, or a reserved storefront collection (cart, save for later) |
| `422`  | First validation error                             | Neither or both user identifiers, or `per_page` outside `1` to `500`                                       |
| `429`  | `Too Many Requests`                                | Rate limit or daily read quota exceeded                                                                    |

---

## Reading a user's favorites {#favorites}

The favorites list is addressed by its slug, so no lookup of the list id is needed:

```
GET /api/v3/lists/favorites/items?user_external_id=student-1042
```

A user who has never favorited anything has no favorites list yet. That is not an error: the endpoint returns an empty page.

```json
{
  "data": [],
  "links": {
    "next": null,
    "prev": null
  },
  "meta": {
    "has_more": false
  }
}
```

---

## See also

- [Lists API Overview](./lists-v3-overview.md)
- [List Lists](./lists-v3-list.md)
- [Manage List Items](./lists-v3-items.md)