--- title: "POST /entities/query" method: POST path: "/entities/query" tags: ["Graph", "Entity"] --- # POST /entities/query `POST /entities/query` ## Headers - `X-Authenticated-User-Actor-Id` string, uuid, required ## Request body - QueryEntitiesRequest - `conversions` QueryConversion[] - `dataTypeId` string, uri, required — The versioned URL of a Block Protocol ontology type (the $id of the schema). It should be of the form `${baseUrl}v/${versionNumber}` - `path` PropertyPathElement[], required - union — An element in a property path that identifies a specific property location. [`PropertyPathElement`] represents a single step in navigating a property hierarchy, addressing either: - A specific property by its type URL (for object properties) - A specific index (for array properties) These elements can be chained together to form a [`PropertyPath`] that addresses deeply nested properties within the property hierarchy. - string, uri — The base URL of a Block Protocol ontology type (the $id of the schema, without the versioned suffix). It should be a valid URL, with a trailing slash. - integer — An array index that addresses a specific element in an array property. - `cursor` object[] - `filter` union, required - object - `all` Filter[], required - object - `any` Filter[], required - object - `not` Filter, required — recursive - object - `equal` FilterExpression[], required - union - PathExpression - `path` union[], required - … - ParameterExpression - `convert` object - … - `parameter` unknown, required - object - `notEqual` FilterExpression[], required - union - PathExpression - `path` union[], required - … - ParameterExpression - `convert` object - … - `parameter` unknown, required - object - `exists` PathExpression, required - `path` union[], required - union - 'baseUrl' | 'version' | 'versionedUrl' | 'webId' | 'title' | 'description' | 'type' | 'inheritsFrom' | 'children' | 'editionProvenance' | 'embedding' — A single token in a [`DataTypeQueryPath`]. - 'baseUrl' | 'version' | 'versionedUrl' | 'webId' | 'title' | 'description' | 'editionProvenance' | 'dataTypes' | 'propertyTypes' | 'embedding' — A single token in a [`DataTypeQueryPath`]. - 'baseUrl' | 'version' | 'versionedUrl' | 'webId' | 'title' | 'description' | 'properties' | 'required' | 'labelProperty' | 'icon' | 'editionProvenance' | 'links' | 'linkDestinations' | 'inheritsFrom' | 'children' | 'embedding' — A single token in a [`EntityTypeQueryPath`]. - 'uuid' | 'editionId' | 'draftId' | 'archived' | 'webId' | 'type' | 'properties' | 'label' | 'createdById' | 'editionCreatedById' | 'createdAtTransactionTime' | 'createdAtDecisionTime' | 'provenance' | 'editionProvenance' | 'embedding' | 'incomingLinks' | 'outgoingLinks' | 'leftEntity' | 'rightEntity' — A single token in an [`EntityQueryPath`]. - '*' - 'convert' - string - number - object - `greater` FilterExpression[] - union - PathExpression - `path` union[], required - … - ParameterExpression - `convert` object - … - `parameter` unknown, required - object - `greaterOrEqual` FilterExpression[] - union - PathExpression - `path` union[], required - … - ParameterExpression - `convert` object - … - `parameter` unknown, required - object - `less` FilterExpression[] - union - PathExpression - `path` union[], required - … - ParameterExpression - `convert` object - … - `parameter` unknown, required - object - `lessOrEqual` FilterExpression[] - union - PathExpression - `path` union[], required - … - ParameterExpression - `convert` object - … - `parameter` unknown, required - object - `startsWith` FilterExpression[], required - union - PathExpression - `path` union[], required - … - ParameterExpression - `convert` object - … - `parameter` unknown, required - object - `endsWith` FilterExpression[], required - union - PathExpression - `path` union[], required - … - ParameterExpression - `convert` object - … - `parameter` unknown, required - object - `containsSegment` FilterExpression[], required - union - PathExpression - `path` union[], required - … - ParameterExpression - `convert` object - … - `parameter` unknown, required - `includeDrafts` boolean, required - `includeEntityTypes` 'closed' | 'resolved' | 'resolvedWithDataTypeChildren' - `includePermissions` boolean, required - `limit` integer, nullable - `sortingPaths` EntityQuerySortingRecord[], nullable - `nulls` 'first' | 'last', required - `ordering` 'ascending' | 'descending', required - `path` union[], required - union - 'uuid' | 'archived' | 'label' | 'editionCreatedAtTransactionTime' | 'editionCreatedAtDecisionTime' | 'createdAtTransactionTime' | 'createdAtDecisionTime' | 'typeTitle' - string - number - `temporalAxes` union, required — Defines the two possible combinations of pinned/variable temporal axes that are used in queries that return [`Subgraph`]s. The [`VariableTemporalAxisUnresolved`] is optionally bounded, in the absence of provided bounds an inclusive bound at the timestamp at point of resolving is assumed. [`Subgraph`]: crate::subgraph::Subgraph - object - `pinned` object, required - `axis` 'transactionTime', required — Time axis for the transaction time. This is used as the generic argument to time-related structs and can be used as tag value. - `timestamp` string, date-time, nullable, required - `variable` object, required - `axis` 'decisionTime', required — Time axis for the decision time. This is used as the generic argument to time-related structs and can be used as tag value. - `interval` UnresolvedRightBoundedTemporalInterval, required - `end` union, required - object - … - object - … - `start` union, required - object - … - object - … - object - … - object - `pinned` object, required - `axis` 'decisionTime', required — Time axis for the decision time. This is used as the generic argument to time-related structs and can be used as tag value. - `timestamp` string, date-time, nullable, required - `variable` object, required - `axis` 'transactionTime', required — Time axis for the transaction time. This is used as the generic argument to time-related structs and can be used as tag value. - `interval` UnresolvedRightBoundedTemporalInterval, required - `end` union, required - object - … - object - … - `start` union, required - object - … - object - … - object - … ## Response `200` A list of entities that satisfy the given query. - QueryEntitiesResponse - `closedMultiEntityTypes` object - `cursor` object[] - `definitions` EntityTypeResolveDefinitions - `dataTypes` object, required - `entityTypes` object, required - `propertyTypes` object, required - `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 - `permissions` object ## Other responses - `422` — Provided query is invalid - `500` — Store error occurred ## Changes - **2026-07-23** `4f728cebf4f4` — 1 breaking - removed the enum value `properties` of the request property `sortingPaths/items/path/items/oneOf[#/components/schemas/EntityQuerySortingToken]/` - **2026-07-10** `0f1f205334eb` — 1 breaking, 50 info - the `entities/items/metadata/provenance` response's property type/format changed from ``/`` to `object`/`` for status `200` - added the new `createdAtDecisionTime` enum value to the request property `filter/oneOf[subschema #10: LessOrEqualFilter]/lessOrEqual/items/oneOf[subschema #1: PathExpression]/path/items/oneOf[#/components/schemas/EntityQueryToken]/` - added the new `createdAtDecisionTime` enum value to the request property `filter/oneOf[subschema #11: StartsWithFilter]/startsWith/items/oneOf[subschema #1: PathExpression]/path/items/oneOf[#/components/schemas/EntityQueryToken]/` - added the new `createdAtDecisionTime` enum value to the request property `filter/oneOf[subschema #12: EndsWithFilter]/endsWith/items/oneOf[subschema #1: PathExpression]/path/items/oneOf[#/components/schemas/EntityQueryToken]/` - …47 more - **2026-07-05** `13f011ab3d7c` — 6 breaking, 3 warning, 5 info - added the new required request property `filter` - added the new required request property `includeDrafts` - added the new required request property `includePermissions` - added the new required request property `temporalAxes` - …10 more - …earlier changes not shown [Full history](https://skmtc.dev/hashintel/apis/graph/changes/entities/query/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)