Traversal Engine

How traversal works

The traversal engine performs a breadth-first search (BFS) starting from a source node and following edges up to a configurable depth.

Source node ──edge──▶ depth 1 ──edge──▶ depth 2 ──edge──▶ depth 3

At each step, visited nodes are tracked to prevent cycles.

Limits

Parameter	Default	Max
depth	2	5
maxVisited	1000	1000

Caution

Traversals deeper than 3 on large, densely connected graphs can be slow. Use filters and direction constraints to reduce the search space.

API

GET /graphs/{graphId}/traverse?sourceId={nodeId}&depth={n}&direction={dir}

Parameters

Parameter	Type	Default	Description
sourceId	string	required	Starting node ID
depth	number	2	Maximum traversal depth
direction	outbound | inbound | both	outbound	Edge direction to follow
edgeType	string	all	Filter by edge type

Response

{
  "source": { "id": "node_1", "type": "Person", "data": { "name": "Alice" } },
  "nodes": [
    { "id": "node_2", "type": "Person", "data": { "name": "Bob" }, "depth": 1 },
    { "id": "node_3", "type": "Company", "data": { "name": "Acme" }, "depth": 2 }
  ],
  "edges": [
    { "id": "edge_1", "type": "KNOWS", "sourceId": "node_1", "targetId": "node_2" },
    { "id": "edge_2", "type": "WORKS_AT", "sourceId": "node_2", "targetId": "node_3" }
  ],
  "visitedCount": 3,
  "depthReached": 2
}

Direction modes

• outbound — follow edges where the source node is the current node (default)
• inbound — follow edges where the target node is the current node
• both — follow all edges regardless of direction

Performance tips

1. Start with depth=2 and increase only if needed.
2. Use edgeType filter to limit the branching factor.
3. For very large graphs (>100K nodes), use the Agentic Query endpoint which combines vector pre-filtering with traversal.