---
title: "POST /entities/search"
method: POST
path: "/entities/search"
tags: ["Graph", "Entity"]
---

# POST /entities/search

`POST /entities/search`

## Headers

- `X-Authenticated-User-Actor-Id` string, uuid, required

## Request body

- SearchEntitiesRequest — Request body for the entity embedding search endpoint. Exactly one of `embedding` or `semanticString` must be provided. `semanticString` is converted into an embedding by the server, which requires an embedding client to be configured.
  - `embedding` number[]
  - `filter` SearchEntitiesFilter — Scope constraints for [`EntityStore::search_entities`]. Empty lists impose no restriction.
    - `entityTypeIds` VersionedUrl[]
    - `includeDrafts` boolean
    - `webIds` WebId[]
  - `includeEntityTypes` boolean
  - `limit` integer, nullable
  - `maximumSemanticDistance` number, double, required
  - `semanticString` string

## Response `200`

Entities ordered by ascending cosine distance to the query embedding.

- SearchEntitiesResponse — Response for [`EntityStore::search_entities`].
  - `closedMultiEntityTypes` object
  - `entities` Entity[], required
    - `linkData` LinkData — The associated information for 'Link' entities.
      - `leftEntityConfidence` number, double
      - `leftEntityId` string, required
      - `leftEntityProvenance` PropertyProvenance
        - `sources` SourceProvenance[]
          - `authors` string[] — The people or organizations that authored the material.
          - `entityId` string
          - `firstPublished` string, date-time
          - `lastUpdated` string, date-time
          - `loadedAt` string, date-time
          - `location` Location — A location where the source material can be found.
            - `description` string — Encapsulates a message intended to be read by the end user.
            - `name` string — A string containing the name of the location.
            - `uri` string, uri — A string containing a valid relative or absolute URI.
          - `type` 'webpage' | 'document' | 'integration', required — The type of source material which was used to produce a value.
      - `rightEntityConfidence` number, double
      - `rightEntityId` string, required
      - `rightEntityProvenance` PropertyProvenance
        - `sources` SourceProvenance[]
          - `authors` string[] — The people or organizations that authored the material.
          - `entityId` string
          - `firstPublished` string, date-time
          - `lastUpdated` string, date-time
          - `loadedAt` string, date-time
          - `location` Location — A location where the source material can be found.
            - `description` string — Encapsulates a message intended to be read by the end user.
            - `name` string — A string containing the name of the location.
            - `uri` string, uri — A string containing a valid relative or absolute URI.
          - `type` 'webpage' | 'document' | 'integration', required — The type of source material which was used to produce a value.
    - `metadata` EntityMetadata, required — Comprehensive metadata for an entity in the knowledge graph. [`EntityMetadata`] contains essential information about an entity beyond its properties, including its identity, temporal versioning, type information, provenance, and confidence. This metadata provides context for interpreting and validating the entity's properties.
      - `archived` boolean, required — Whether this entity has been archived. Archived entities are generally not included in regular queries but remain in the system for historical purposes. Note, that this will be replaced by cutting off the temporal versioning interval at the current transaction time in the future. This is a stopgap measure to ensure that archived entities are possible at the time of writing.
      - `confidence` number, double
      - `entityTypeIds` VersionedUrl[], required — The set of entity types this entity conforms to. Each entity must conform to at least one entity type, and may conform to multiple types simultaneously.
      - `properties` PropertyObjectMetadata
        - `metadata` ObjectMetadata
          - `confidence` number, double
          - `provenance` PropertyProvenance
            - `sources` SourceProvenance[]
              - …
        - `value` object, required — Metadata for each field in the object. The keys correspond to the property type URLs used in the object property.
      - `provenance` EntityProvenance, required
        - `createdAtDecisionTime` string, date-time, required
        - `createdAtTransactionTime` string, date-time, required
        - `createdById` string, uuid, required
        - `deletedAtDecisionTime` string, date-time
        - `deletedAtTransactionTime` string, date-time
        - `deletedById` string, uuid
        - `edition` EntityEditionProvenance, required
          - `actorType` 'user' | 'machine' | 'ai', required — Types of individual actors in the system. Represents the different categories of entities that can perform actions.
          - `origin` union, required
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
          - `sources` SourceProvenance[]
            - `authors` string[] — The people or organizations that authored the material.
            - `entityId` string
            - `firstPublished` string, date-time
            - `lastUpdated` string, date-time
            - `loadedAt` string, date-time
            - `location` Location — A location where the source material can be found.
              - …
            - `type` 'webpage' | 'document' | 'integration', required — The type of source material which was used to produce a value.
          - `archivedById` string, uuid
          - `createdById` string, uuid, required
        - `firstNonDraftCreatedAtDecisionTime` string, date-time
        - `firstNonDraftCreatedAtTransactionTime` string, date-time
      - `readOnly` boolean — Whether this entity is read-only and must not be modified by user actors.
      - `recordId` EntityRecordId, required
        - `editionId` string, uuid, required
        - `entityId` string, required
      - `temporalVersioning` EntityTemporalMetadata, required — Temporal metadata for tracking entity versions over time. [`EntityTemporalMetadata`] tracks two distinct time dimensions: - Decision time: When the entity was decided to exist in the real world - Transaction time: When the entity was recorded in the system This bi-temporal approach allows precise tracking of when information was known versus when it was recorded, enabling accurate historical queries.
        - `decisionTime` LeftClosedTemporalInterval, required
          - `end` union, required
            - object
              - …
            - object
              - …
          - `start` ClosedTemporalBound, required
            - `kind` 'inclusive', required
            - `limit` string, date-time, required
        - `transactionTime` LeftClosedTemporalInterval, required
          - `end` union, required
            - object
              - …
            - object
              - …
          - `start` ClosedTemporalBound, required
            - `kind` 'inclusive', required
            - `limit` string, date-time, required
    - `properties` PropertyObject, required

## Other responses

- `400` — Provided request body is invalid
- `500` — Store error occurred

## Changes

> 51 revisions in range; 33 could not be searched.

- **2025-04-24** `ccac01e6aad0` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/hashintel/apis/graph/changes/entities/search/post.md)

---

[API](https://skmtc.dev/hashintel/apis/graph.md) · [All operations](https://skmtc.dev/hashintel/apis/graph/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hashintel/graph/revisions/ba95e69ddba8/schema)