> ## 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 Entity by Foreign ID

> Get an entity by its foreign ID, optionally creating it if not found

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

Returns an entity matching the given `foreignId` within the project. Optionally creates a blank entity if none exists — useful for automatically bootstrapping entities when a user first visits a page or URL in your application.

## Query Parameters

<ParamField query="foreignId" type="string" required>
  The foreign ID to look up. This is the identifier from your application (URL, slug, database ID, etc.).
</ParamField>

<ParamField query="createIfNotFound" type="string">
  When `"true"`, creates a blank entity with this `foreignId` if no entity is found. The new entity has no title, content, or user attribution. Defaults to `"false"`.
</ParamField>

<ParamField query="include" type="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](/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.

## Response

Returns an [Entity](/v8/data-models/entity) object.

<Note>
  This endpoint returns entities regardless of moderation status, so the client can display the appropriate moderation state. Draft entities are only returned to their author (or with a service/master key).
</Note>

## Error Responses

<AccordionGroup>
  <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>

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

    Returned when no entity with this `foreignId` exists and `createIfNotFound` is not `"true"`.
  </Accordion>
</AccordionGroup>


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