Skip to main content
Fetch Collection Entities
Returns a paginated list of entities saved in the specified collection. The collection must belong to the authenticated user.

Path Parameters

string
required
The ID of the collection to fetch entities from.

Query Parameters

number
Page number (1-indexed). Default: 1.
number
Number of entities per page. Default: 20.
"createdAt" | "addedAt" | "top" | "hot"
Sort mode. Default: "createdAt".
  • createdAt — by when the entity was created
  • addedAt — 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.
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.
"asc" | "desc"
Sort direction, "asc" or "desc" (either case). Default: "desc". Not accepted with "hot", which ranks one way only (hottest first): sending it returns 400 collection/invalid-query.
string
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 objects (see Top comments)
  • files — uploaded file/image attachments
  • grants — the reputation-grant summary for the entity
saved isn’t accepted here (400 collection/invalid-query): every entity returned by this endpoint already has isSaved: true.
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.
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.
string
Service key only, and required with one: the user this request acts as. Must own the collection. A user token always acts as its own user and must not send it (400 collection/acting-user-not-allowed).
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

Entity[]
The page of entity objects. Each entity includes isSaved: true.
object
Pagination metadata.

Error Responses

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.
include=topComment is rejected with a pointer to its replacement.
sortBy=new and sortBy=added are rejected with a pointer to their replacements: sortBy=createdAt (when the entity was created) and sortBy=addedAt (when it was added to the collection).
Returned when a query parameter is invalid, including sortByReaction sent without sortBy=top.
A service key sent no actingUserId.
A user token sent actingUserId, even naming its own user. Only a service key names the user it acts as; a user token always acts as its own user.
Returned when a service key names an actingUserId that isn’t a user in this project.
The request sent userId. On this route the user a service key acts as is actingUserId.With a service key:
With a user token, or with no credentials: