get_dependency_tree
Walk the dependency tree from a CI in ServiceNow CMDB. Choose upstream or downstream, set depth and class filters to trace what a CI depends on or what depends on it.
Instructions
Walk the dependency tree from a CI with configurable depth and direction.
Recursively traverses relationships to build a tree of dependencies. Useful for understanding the full dependency chain of a CI — what it runs on, what runs on it.
Prerequisites: Use search_cis to find the root CI sys_id first.
Performance: API calls grow exponentially with max_depth — depth=3 with limit_per_level=10 can issue up to ~111 calls. Start with max_depth=2 and increase only if needed. Reduce limit_per_level for wide graphs. A hard 60-second timeout applies; on timeout only the root node is returned (in-progress subtrees are discarded) with timed_out=true.
Examples: get_dependency_tree(ci_sys_id="abc123...", direction="downstream", max_depth=2) get_dependency_tree(ci_sys_id="abc123...", class_filter=["cmdb_ci_linux_server", "cmdb_ci_win_server"]) get_dependency_tree(ci_sys_id="abc123...", format="ascii_tree", max_depth=3)
Args: ci_sys_id: The sys_id of the starting CI (32-character hex string from search_cis). direction: Direction to traverse: "upstream" (what this CI depends on) or "downstream" (what depends on this CI). Defaults to "upstream". max_depth: How many levels deep to traverse (1-5, default 3). Higher values make more API calls. Capped at 5 to prevent runaway traversals. limit_per_level: Maximum CIs to follow at each level (default 10). Controls breadth of the tree to avoid excessive API calls. class_filter: Optional list of sys_class_name values to include in the tree. Only CIs matching these classes appear in the output. CIs that don't match are still traversed (their children may match), but they are collapsed out of the result. When None or empty, all classes are included. Example: ["cmdb_ci_server", "cmdb_ci_linux_server"]. format: Output format. "json" (default) returns the nested tree structure. "ascii_tree" returns a pre-rendered text tree — much smaller, readable without post-processing, but loses sys_id and status detail.
Returns: When format="json" (default): JSON object with "ci" (root CI), "direction", "max_depth", "nodes_visited", "tree" (nested children), and "suggested_next". When format="ascii_tree": the "tree" field is replaced by "tree_text" (pre-rendered ASCII string). Both shapes also include "class_filter" when applied, "timed_out" on deadline hit, and "is_partial" + "traversal_errors" if any nodes failed to resolve.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ci_sys_id | Yes | ||
| direction | No | upstream | |
| max_depth | No | ||
| limit_per_level | No | ||
| class_filter | No | ||
| format | No | json |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |