Graph Traversal reference
Reference for the InfrahubPathTraversal and InfrahubReachableNodes GraphQL queries.
InfrahubPathTraversal​
Input type: PathTraversalInput
| Argument | Type | Required | Default | Max | Description |
|---|---|---|---|---|---|
source_id | String | Yes | — | — | UUID of the start node |
destination_id | String | Yes | — | — | UUID of the end node |
max_depth | Int | No | 5 | 30 | Maximum number of hops |
max_paths | Int | No | 10 | 100 | Maximum paths to return |
kind_filter | [String] | No | — | — | Limit traversal to these kinds only |
relationship_filter | [String] | No | — | — | Limit traversal to these relationship identifiers (schema identifier, e.g. device__interface) |
excluded_namespaces | [String] | No | — | — | Additional namespaces to exclude; unioned with defaults |
excluded_kinds | [String] | No | — | — | Additional kinds to exclude; unioned with defaults |
included_kinds | [String] | No | — | — | Re-include kinds excluded by default. API only — not available in the UI. |
Response type: PathTraversalResultType
| Field | Type | Description |
|---|---|---|
count | Int | Number of paths found |
paths | [PathResultType] | Paths found, ordered shortest first |
source | PathNodeType | The start node |
destination | PathNodeType | The end node |
excluded_kinds | [String] | All kinds excluded in this traversal |
Each PathResultType has depth (number of edges) and hops — an ordered list where each hop
has a node and (except the first) a relationship. Each node (PathNodeType) exposes id,
kind, label, display_label, and hfid. Each relationship (PathRelationshipType) exposes
from_rel, from_label, to_rel, to_label, and kind.
InfrahubReachableNodes​
Input type: ReachableNodesInput
| Argument | Type | Required | Default | Max | Description |
|---|---|---|---|---|---|
source_id | String | Yes | — | — | UUID of the source node |
target_kinds | [String] | Yes | — | — | Kinds to search for; at least one required |
max_depth | Int | No | 5 | 30 | Maximum hops to traverse |
max_results | Int | No | 50 | 200 | Maximum distinct target nodes to find. Labeled Max Targets in the UI. |
max_paths | Int | No | 500 | 5000 | Maximum total paths across all targets |
shortest_paths_only | Boolean | No | true | — | When true, return only the shortest path to each target. When false, return every path within max_depth. |
Response type: ReachableNodesResultType
| Field | Type | Description |
|---|---|---|
count | Int | Number of dependency entries returned |
source | PathNodeType | The source node |
dependencies | [ReachableNodeType] | One entry per reachable node |
Each ReachableNodeType has node, depth (hops from source), and path (full path from
source to this node).
Default exclusions​
| Excluded by default | Can be re-included |
|---|---|
Core, Internal, Builtin, Lineage, Profile, Template namespaces | No |
BuiltinIPNamespace and all kinds that inherit it | Yes — via included_kinds in InfrahubPathTraversal (API only) |
Use excluded_namespaces or excluded_kinds to add further exclusions.
Common errors​
| Error | Cause | Fix |
|---|---|---|
Source and destination nodes must be different | source_id equals destination_id | Use two distinct UUIDs |
At least one target kind is required | target_kinds is empty | Provide at least one kind |
Unknown target kind: <kind> | Kind not found in schema | Check the kind name against your schema |
Source node not found: <id> | UUID does not exist on this branch | Verify the UUID and branch |
Destination node not found: <id> | Destination UUID does not exist on this branch | Verify the UUID and branch |
max_paths must be in [1, 100] | Out of range for Path mode | Use a value between 1 and 100 |
| Query timed out | Search space too large | Reduce max_depth, lower max_paths/max_results, or narrow with kind/namespace filters |