---
title: "Get search by ID"
method: GET
path: "/search/{searchId}"
tags: ["Semantic Search"]
---

# Get search by ID

`GET /search/{searchId}`

Retrieve a previously persisted search by its id, scoped to the
caller's org.

The response body is always an **array** containing zero or one
persisted search document. An unknown id returns an empty array
with a `200` status — callers should check array length rather
than relying on a `404`.

## Path parameters

- `searchId` string, objectId, required

## Response `200`

Array containing zero or one persisted search document.

- PersistedSemanticSearch[] — GET `/search/{searchId}` calls `Model.find()` (not `findOne()`) and sends the result as-is, so the wire format is an array of zero or one persisted search docs. A non-existent id returns `200 []`, **not** `404`.
  - `_id` string, objectId, required
  - `__v` integer, required
  - `query` string, required
  - `limit` integer, required
  - `orgId` string, objectId, required
  - `userId` string, objectId, required
  - `citationIds` PersistedSemanticSearchCitation[], required
    - `_id` string, objectId, required
    - `content` string, required
    - `chunkIndex` integer, required
    - `citationType` string, required
    - `metadata` PersistedSemanticSearchCitationMetadata, required — Citation metadata as persisted in MongoDB. Required fields mirror the Mongoose schema's `required: true` flags; the rest are optional and may come through as `null` because the AI retrieval service emits explicit nulls for absent fields.
      - `orgId` string, required
      - `mimeType` string, required
      - `recordId` string, required
      - `recordName` string, required
      - `origin` string, required
      - `recordVersion` integer, nullable
      - `extension` string, nullable
      - `webUrl` string, nullable
      - `previewRenderable` boolean, nullable
      - `hideWeburl` boolean, nullable
      - `connector` string, nullable
      - `recordType` string, nullable
      - `blockNum` number[], nullable
      - `pageNum` number[], nullable
      - `sheetNum` number, nullable
      - `sheetName` string, nullable
      - `bounding_box` PersistedSemanticSearchBoundingBox[], nullable
        - `_id` string, objectId, required
        - `x` number, required
        - `y` number, required
      - `blockType` string, nullable — Block type for this citation. Common values: `text`, `image`, `table_row`, `table`, `record_summary` (whole-record semantic summary chunk).
      - `blockText` string, nullable
      - `departments` string[], nullable
      - `languages` string[], nullable
      - `topics` string[], nullable
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
  - `records` object, required — Map of source-record id (or `_key`) to a JSON-stringified record object. Clients must `JSON.parse` each value before reading fields.
  - `isShared` boolean, required
  - `shareLink` string — Set once the search has been shared via `/search/{searchId}/share`.
  - `sharedWith` PersistedSemanticSearchSharedWithEntry[], required
    - `userId` string, objectId, required
    - `accessLevel` 'read' | 'write', required
  - `isArchived` boolean, required
  - `archivedBy` string, objectId, nullable — User ID of the last user who archived this row, or `null` after an unarchive cleared the archive state. Absent on rows that have never been archived. Currently-archived rows cannot reach this endpoint because `buildFilter` enforces `isArchived: false`.
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required

## Other responses

- `400` — Invalid request — `searchId` failed Zod validation (not a valid ObjectId).
- `401` — Missing or invalid bearer token.
- `403` — Bearer token lacks the `semantic:read` scope.
- `404` — Reserved for parity with sibling routes; this endpoint currently returns `200` with an empty array for an unknown id rather than emitting `404`.
- `500` — Server error. Possible causes: - Explicit `InternalServerError` or any other 500 `BaseError` thrown by the handler. - Non-`BaseError` exception caught by the global error middleware. - Response serializer fallback.

---

[API](https://skmtc.net/pipeshub-ai/apis/pipeshub-api.md) · [All operations](https://skmtc.net/pipeshub-ai/apis/pipeshub-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pipeshub-ai/pipeshub-api/versions/abd27cfefc73/schema)