---
title: "queryEntityGraph"
method: POST
path: "/v1/entity:graph"
tags: ["Entities"]
---

# queryEntityGraph

`POST /v1/entity:graph`

Traverse an entity relationship graph starting from a seed entity.

Define the shape of the graph using nodes (entity schemas) and edges (relationships with cardinality).
The API will traverse the graph bidirectionally and return all discovered entity IDs.

Example: Find all entities connected to a contact through portal_user -> contact -> billing_account -> files

## Request body

- GraphQueryRequest
  - `seed` GraphSeed, required
    - `entity_id` string, uuid, required
    - `node_id` string, required — The node ID in the graph definition that corresponds to the seed entity
  - `graph` GraphDefinition, required
    - `nodes` GraphNode[], required — List of node definitions in the graph
      - `id` string, required — Unique identifier for this node in the graph definition
      - `schema` string, required — Entity schema slug for this node
      - `cardinality` 'one' | 'many' — Optional cardinality for this node when used with hydrate=true: - "one": Node can only contain one entity, return single Entity object in entityNodes - "many": Node can contain multiple entities, return array of Entity objects in entityNodes If not specified, defaults to "many" (returns array). The seed node always returns a single entity regardless of this setting.
      - `fields` string[] — Optional array of field names to include in the hydrated entity response for this node. When specified, only the requested fields plus required internal fields (_id, _schema, _org) will be returned. Only applies when hydrate=true.
    - `edges` GraphEdge[], required — List of edge definitions connecting nodes
      - `from` string, required — Source node ID
      - `to` string, required — Target node ID
  - `hydrate` boolean — If true, return full entity objects in entityNodes instead of just entity IDs in nodes
  - `apply_changesets` boolean — When true and hydrate is also true, entity objects in entityNodes have pending changeset proposed values applied in-place. The _changesets field is still included in the response.

## Response `200`

Graph traversal result

- GraphQueryResponse
  - `nodes` object — Map of node IDs to arrays of entity IDs found for that node (present when hydrate=false)
  - `entityNodes` object — Map of node IDs to entity objects or arrays of entity objects (present when hydrate=true). The seed node and nodes with cardinality="one" return a single Entity object, or null if no entity was found. Nodes with cardinality="many" return an array of Entity objects.
  - `edges` GraphEdge[], required — List of edges as defined in the request
    - `from` string, required — Source node ID
    - `to` string, required — Target node ID

## Other responses

- `400` — Bad request - invalid input parameters
- `404` — The requested resource was not found

---

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