Skip to main content
Fetch Many Entities
Requires the entities bundle. A project without the entities bundle returns 403 database/tables-not-available. See Bundles.
Returns a paginated list of entities for the project. Supports rich filtering by source, space, user, keywords, metadata, title, content, location, and time. Excludes drafts — use Fetch Drafts for those.

Query Parameters

Pagination

number
default:"1"
Page number (1-indexed).
number
default:"10"
Number of entities per page. Maximum 100.

Sorting

string
default:"createdAt"
Sort algorithm. One of:
  • createdAt — chronological by creation time (honors sortDir; newest first by default)
  • top — by reaction count (use sortByReaction to specify which type)
  • hot — by computed engagement score (decays over time)
  • controversial — high total votes with a close up/down split (entities with no votes sort last)
  • metadata.<property> — sort by a metadata field (e.g. metadata.memberCount)
new is a deprecated alias for createdAt (removed in v8). It still works and behaves identically, but requests using it receive a non-blocking Deprecation response header — switch to createdAt.
string
default:"DESC"
Sort direction. ASC or DESC.
string
default:"auto"
When using sortBy=metadata.*, the type of the metadata field. One of auto, numeric, text, boolean, timestamp. auto infers the type at query time.
string
default:"upvote"
When sortBy=top, which reaction type to rank by. One of upvote, downvote, like, love, wow, sad, angry, funny.

Filtering

string
Restrict to entities created within the last period. One of hour, day, week, month, year.
string
Filter by sourceId. Pass "null" to return entities with no sourceId.
string
Filter by space ID.
string
Filter by the author’s user ID. When this matches the authenticated user’s ID, moderation-removed entities are also included (author can see their own removed posts).
string
When "true", only returns entities from users the authenticated user follows. Requires authentication.
string
default:"exclude"
Controls how entities authored by users the viewer is block-edged with are treated. "exclude" (default) hides those entities. "include-outbound-blocked" re-includes entities authored only by users the viewer themselves blocked (their own “view anyway” choice); it never surfaces content from users who blocked the viewer. Counts reflect what the viewer sees (computed post-filter). Has no effect when the moderation bundle is not installed.
object
Filter by keywords. Pass as a JSON string or bracket-notation query params:
object
Filter by title content:
  • hasTitle: "true" or "false" — filter for presence/absence of a title
  • includes: substring(s) to match (case-insensitive)
  • doesNotInclude: substring(s) to exclude
object
Filter by content text. Same structure as titleFilters (hasContent, includes, doesNotInclude).
object
Filter by attachment presence:
object
Filter to entities within a radius of a point:
radius is in meters.
object
Filter by metadata values. Supports complex conditions:
  • includes — all key/value pairs must match (AND)
  • includesAny — at least one object must match (OR)
  • doesNotInclude — none of these key/value pairs may match
  • exists — keys that must be present
  • doesNotExist — keys that must be absent

Optional Associations

string
Comma-separated list of associations to include in each entity:
  • user — the author’s user profile
  • space — the space the entity belongs to
  • topComment — the highest-voted comment
  • saved — whether the authenticated user has saved this entity
  • files — uploaded file/image attachments
  • grants — the reputation-grant summary for the entity

Space-scoped reputation

This endpoint has a space in context, so it accepts the opt-in reputation params. They add a spaceReputation field to each populated author user, alongside the always-present reputation total. Requires the reputation bundle. See the Reputation data model for the full contract.

Response

Returns a paginated response object:
Each item in data is an Entity object. File URLs are signed and ready to use.
Viewing scores (hot sort) are updated asynchronously after each fetch. Scores use a configurable half-life that can be set per project in your project settings.

See Also