> ## 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 Many Entities

> Get a paginated, filtered list of entities

export const SpaceReputationParams = ({variant = "context", field = "path"}) => {
  const isUser = variant === "user";
  return <>
      <ParamField {...{
    [field]: "spaceReputation",
    type: "object"
  }}>
        Opt-in. Adds a <code>spaceReputation</code> number to each returned user,
        scoped to a single space. Requires the <code>reputation</code> bundle.
        The <code>reputation</code> total is always present regardless;{" "}
        <code>spaceReputation</code> is purely additive and only appears when you
        pass this object. <strong>This object is the primary form</strong> — it
        replaces the deprecated flat props below. See the{" "}
        <a href="/v8/data-models/reputation">Reputation data model</a> for the
        full contract.

        <Expandable title="spaceReputation">
          {isUser ? <ParamField name="spaceId" type="string | &quot;none&quot;" required>
              Which bucket to read. A space <strong><code>&lt;uuid&gt;</code></strong> reads that
              space's bucket; <strong><code>"none"</code></strong> reads the
              project-general (space-less) bucket.{" "}
              <strong><code>"context"</code> is rejected (400)</strong> on this
              endpoint — there is no space context to derive. The empty string
              and the legacy <code>general</code> / <code>null</code> aliases are
              also rejected. Missing buckets read as <code>0</code>.
            </ParamField> : <ParamField name="spaceId" type="string | &quot;none&quot; | &quot;context&quot;" required>
              Which bucket to read. One of: a space <strong><code>&lt;uuid&gt;</code></strong>{" "}
              (that space's bucket), <strong><code>"none"</code></strong> (the
              project-general, space-less bucket), or{" "}
              <strong><code>"context"</code></strong> (the space derived from the
              request context — resolved per-row on lists, or the single space on
              member/team/conversation surfaces). The empty string and the legacy{" "}
              <code>general</code> / <code>null</code> aliases are rejected (400).
              Missing buckets read as <code>0</code>.
            </ParamField>}
          <ParamField name="includeDescendants" type="boolean">
            Only honored when <code>spaceId</code> is an explicit space <code>&lt;uuid&gt;</code>.
            When <code>true</code>, <code>spaceReputation</code> is the{" "}
            <strong>subtree sum</strong> — the named space plus all of its
            descendant spaces (the root space's own bucket included). Ignored for{" "}
            <code>"none"</code>; not allowed with <code>"context"</code>.
          </ParamField>
        </Expandable>
      </ParamField>

      {isUser ? <ParamField {...{
    [field]: "spaceReputationId",
    type: "string",
    deprecated: true
  }}>
          <strong>Deprecated</strong> — use the <code>spaceReputation</code>{" "}
          object instead. The flat form of <code>spaceReputation.spaceId</code>.
          Still accepted (the object wins if both are passed); removal is a later
          major version. Accepts a space <code>&lt;uuid&gt;</code> or <code>"none"</code> only —{" "}
          <code>"context"</code> is rejected (400) on this endpoint.
        </ParamField> : <ParamField {...{
    [field]: "spaceReputationId",
    type: "string",
    deprecated: true
  }}>
          <strong>Deprecated</strong> — use the <code>spaceReputation</code>{" "}
          object instead. The flat form of <code>spaceReputation.spaceId</code>.
          Still accepted (the object wins if both are passed); removal is a later
          major version. Accepts a space <code>&lt;uuid&gt;</code>, <code>"none"</code>, or{" "}
          <code>"context"</code>.
        </ParamField>}

      <ParamField {...{
    [field]: "spaceReputationDescendants",
    type: "boolean",
    deprecated: true
  }}>
        <strong>Deprecated</strong> — use{" "}
        <code>spaceReputation.includeDescendants</code> instead. The flat form,
        only honored alongside an explicit <code>spaceReputationId</code> <code>&lt;uuid&gt;</code>.
      </ParamField>
    </>;
};

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/v8/bundles).
</Note>

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](/v8/api-reference/entities/fetch-drafts) for those.

## Query Parameters

### Pagination

<ParamField query="page" type="number" default="1">
  Page number (1-indexed). A whole number of at least `1` — `0`, a negative number or a non-integer value returns `400 entity/invalid-query`.
</ParamField>

<ParamField query="limit" type="number" default="10">
  Number of entities per page. A whole number of at least `1` — `0`, a negative number or a non-integer value returns `400 entity/invalid-query`. Maximum `100` — larger values are treated as `100`.
</ParamField>

### Sorting

<ParamField query="sortBy" type="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`)
</ParamField>

<Note>
  `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`.
</Note>

<ParamField query="sortDir" type="string" default="DESC">
  Sort direction. `ASC` or `DESC`.
</ParamField>

<ParamField query="sortType" type="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.
</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 entity/invalid-query`.
</ParamField>

### Filtering

<ParamField query="timeFrame" type="string">
  Restrict to entities created within the last period. One of `hour`, `day`, `week`, `month`, `year`.
</ParamField>

<ParamField query="sourceId" type="string">
  Filter by `sourceId`. Pass `"null"` to return entities with no `sourceId`.
</ParamField>

<ParamField query="spaceId" type="string">
  Filter by space ID.
</ParamField>

<ParamField query="userId" type="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).
</ParamField>

<ParamField query="followedOnly" type="string">
  When `"true"`, only returns entities from users the authenticated user follows. Requires authentication.
</ParamField>

<ParamField query="blockedFilter" type="string" default="exclude">
  Controls how entities authored by users the viewer is [block-edged](/v8/sdk/moderation/overview#blocking) 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.
</ParamField>

<ParamField query="keywordsFilters" type="object">
  Filter by keywords. Pass as a JSON string or bracket-notation query params:

  ```json theme={null}
  { "includes": ["react", "typescript"], "doesNotInclude": ["vue"] }
  ```
</ParamField>

<ParamField query="titleFilters" type="object">
  Filter by title content:

  ```json theme={null}
  {
    "hasTitle": "true",
    "includes": "tutorial",
    "doesNotInclude": "beginner"
  }
  ```

  * `hasTitle`: `"true"` or `"false"` — filter for presence/absence of a title
  * `includes`: substring(s) to match (case-insensitive)
  * `doesNotInclude`: substring(s) to exclude
</ParamField>

<ParamField query="contentFilters" type="object">
  Filter by content text. Same structure as `titleFilters` (`hasContent`, `includes`, `doesNotInclude`).
</ParamField>

<ParamField query="attachmentsFilters" type="object">
  Filter by attachment presence:

  ```json theme={null}
  { "hasAttachments": "true" }
  ```
</ParamField>

<ParamField query="locationFilters" type="object">
  Filter to entities within a radius of a point:

  ```json theme={null}
  { "latitude": "40.7128", "longitude": "-74.0060", "radius": "5000" }
  ```

  `radius` is in meters.
</ParamField>

<ParamField query="metadataFilters" type="object">
  Filter by metadata values. Supports complex conditions:

  ```json theme={null}
  {
    "includes": { "status": "published" },
    "includesAny": [{ "type": "video" }, { "type": "image" }],
    "doesNotInclude": { "hidden": true },
    "exists": ["category"],
    "doesNotExist": ["archivedAt"]
  }
  ```

  * `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
</ParamField>

### Optional Associations

<ParamField query="include" type="string">
  Associations to include in each entity. 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))
  * `saved` — whether the authenticated user has saved this entity
  * `files` — uploaded file/image attachments
  * `grants` — the [reputation-grant summary](/v8/data-models/reputation-grant#grantsummary) for the entity
</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 entity/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 entity/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.

### 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](/v8/data-models/reputation) for the full contract.

<SpaceReputationParams variant="context" field="query" />

## Response

Returns a paginated response object:

```json theme={null}
{
  "data": [ ...Entity[] ],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "totalPages": 5,
    "totalItems": 42,
    "hasMore": true
  }
}
```

Each item in `data` is an [Entity](/v8/data-models/entity) object. File URLs are signed and ready to use.

<Note>
  Viewing scores (`hot` sort) are updated asynchronously after each fetch. Scores decay at a rate set per project ([feed decay](/v8/sdk/entity-lists/fetch-entities#feed-decay)). Entities with equal scores are ordered newest first.
</Note>

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid Query — 400">
    Returned when `page` or `limit` is below `1` or not a whole number.

    ```json theme={null}
    { "error": "page: Page must be a positive integer", "code": "entity/invalid-query" }
    ```
  </Accordion>

  <Accordion title="Invalid include — 400">
    Returned with code `entity/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, saved, files, grants.", "code": "entity/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": "entity/unsupported-param",
      "param": "include"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [Reputation data model](/v8/data-models/reputation) — the `spaceReputation` object contract
* [Entity data model](/v8/data-models/entity)


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