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

# Fetch Collection Entities

> Get paginated entities saved in a collection

Returns a paginated list of entities saved in the specified collection. The collection must belong to the authenticated user.

## Path Parameters

<ParamField path="collectionId" type="string" required>
  The ID of the collection to fetch entities from.
</ParamField>

## Query Parameters

<ParamField query="page" type="number" optional>
  Page number (1-indexed). Default: `1`.
</ParamField>

<ParamField query="limit" type="number" optional>
  Number of entities per page. Default: `20`.
</ParamField>

<ParamField query="sortBy" type="&#x22;new&#x22; | &#x22;top&#x22; | &#x22;hot&#x22; | &#x22;added&#x22;" optional>
  Sort mode. Default: `"new"`.

  * `new` — by when the entity was created
  * `added` — by when the entity was saved to this collection
  * `top` — by reaction count (use `sortByReaction` to choose which reaction)
  * `hot` — by computed engagement score (decays over time)

  The whole collection is sorted before it is paginated. Ties in `top` and `hot` are broken by newest entity first.
</ParamField>

<ParamField query="sortByReaction" type="string" default="upvote">
  When `sortBy=top`, which reaction type to rank by. One of `upvote`, `downvote`, `like`, `love`, `wow`, `sad`, `angry`, `funny`. Only accepted with `sortBy=top`; sending it with any other sort returns `400 collection/invalid-query`.
</ParamField>

<ParamField query="sortDir" type="&#x22;asc&#x22; | &#x22;desc&#x22;" optional>
  Sort direction. Default: `"desc"`.
</ParamField>

<ParamField query="include" type="string" optional>
  Associations to include. Pass it as one comma-separated value (`include=user,space`) or as repeated params (`include=user&include=space`). Values:

  * `user` — the author's user profile
  * `space` — the space the entity belongs to
  * `topComments` — the entity's best top-level comments, as full [Comment](/v8/data-models/comment) objects (see [Top comments](/v8/data-models/entity#top-comments))
  * `files` — uploaded file/image attachments
  * `grants` — the [reputation-grant summary](/v8/data-models/reputation-grant#grantsummary) for the entity

  `saved` isn't accepted here (`400 collection/invalid-query`): every entity returned by this endpoint already has `isSaved: true`.
</ParamField>

<ParamField query="topCommentsLimit" type="number" default="1">
  With `include=topComments`: how many top comments per entity. A whole number of at least `1` — `0`, a negative number or a non-integer value returns `400 collection/invalid-query`. Maximum `5` — larger values are treated as `5`.
</ParamField>

<ParamField query="topCommentsSortByReaction" type="string" default="upvote">
  With `include=topComments`: the reaction whose raw count ranks the top comments (ties newest first). One of `upvote`, `downvote`, `like`, `love`, `wow`, `sad`, `angry`, `funny`.
</ParamField>

`include` values are case-insensitive. An unknown value returns `400 collection/invalid-query`, as does sending `topCommentsLimit` or `topCommentsSortByReaction` without `include=topComments`. `topComments` lists real content only — deleted, removed and block-edged comments are left out — and is `[]` when nothing qualifies. A collection keeps an entity saved before its author blocked the requesting user; on such an entity `topComments` is always `[]`.

## Response

<ResponseField name="data" type="Entity[]">
  The page of entity objects. Each entity includes `isSaved: true`.
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata.

  <Expandable>
    <ResponseField name="page" type="number">Current page.</ResponseField>
    <ResponseField name="pageSize" type="number">Page size.</ResponseField>
    <ResponseField name="totalPages" type="number">Total number of pages.</ResponseField>
    <ResponseField name="totalItems" type="number">Number of saved entities the list can return. Entities deleted, removed by moderation, or turned back into drafts after being saved are not counted.</ResponseField>
    <ResponseField name="hasMore" type="boolean">`true` if more pages exist.</ResponseField>
  </Expandable>
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid include — 400">
    Returned with code `collection/invalid-query` for an unknown `include` value, when `topCommentsLimit` is below `1` or not a whole number, or when `topCommentsLimit` / `topCommentsSortByReaction` is sent without `include=topComments`.

    ```json theme={null}
    { "error": "include: Unknown include `comments`. Allowed: user, space, topComments, files, grants.", "code": "collection/invalid-query" }
    ```
  </Accordion>

  <Accordion title="Renamed include — 400">
    `include=topComment` is rejected with a pointer to its replacement.

    ```json theme={null}
    {
      "error": "`include=topComment` was renamed to `topComments` (with `topCommentsLimit` / `topCommentsSortByReaction`).",
      "code": "collection/unsupported-param",
      "param": "include"
    }
    ```
  </Accordion>

  <Accordion title="Invalid Query — 400">
    Returned when a query parameter is invalid, including `sortByReaction` sent without `sortBy=top`.

    ```json theme={null}
    { "error": "sortByReaction: sortByReaction is only supported with sortBy=top", "code": "collection/invalid-query" }
    ```
  </Accordion>

  <Accordion title="Collection Not Found — 404">
    ```json theme={null}
    { "error": "Collection not found", "code": "collection/not-found" }
    ```
  </Accordion>

  <Accordion title="Server Error — 500">
    ```json theme={null}
    { "error": "Internal server error.", "code": "collection/server-error" }
    ```
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.