get_nodes_info
Retrieve detailed properties of Figma nodes with recursive subtree traversal, property filtering, and depth control. Ideal for extracting node data like fills, strokes, or layout settings.
Instructions
Get detailed information about one or more nodes. Supports recursive subtree traversal, property filtering, and streaming progress.
If no nodeIds are provided, the tool defaults to the current 'editable scope' (the node(s) selected when the plugin was opened).
Properties: When 'fields' is empty, only 'id', 'name', and 'type' are returned for each node. To get more data, specify fields from Figma's REST API (e.g., 'fills', 'strokes', 'characters', 'layoutMode').
Safe-list: Common properties like 'id', 'name', 'type', 'visible', 'locked', 'children', and 'descendantCount' are always available and do not incur additional performance cost.
Filtering: Use the 'filter' object to prune the tree (e.g., {"type": ["TEXT", "COMPONENT"]}). A node is included if it matches the filter OR has matching descendants.
Depth: 'maxDepth' controls how deep the recursive walk goes. Use 0 for just the target nodes, or higher for subtrees. Boundary nodes at maxDepth will include a 'descendantCount'.
Performance: This tool streams progress updates and is safe for deep traversals.
RESPONSE SHAPE:
Returns { nodes: [...], missingNodeIds?: [...] }. Each node has recursive 'children' arrays. When 'fields' is non-empty, every node (top-level and descendants) carries a 'properties' sub-object with only applicable keys — inapplicable keys are omitted (never null). Top-level entries always include 'descendantCount' (total recursive descendants). Boundary nodes at 'maxDepth' also include 'descendantCount' so you can distinguish truncated nodes from genuine leaves.
PATH:
Each top-level node includes a 'path' array of 3-tuples [type, id, name] representing the ancestor chain from the containing page down to the immediate parent. Pages have path === []. Direct children of a page have one element.
FILTER BEHAVIOR:
Filters are applied recursively across the entire subtree. Non-matching ancestors of matching nodes are retained as structural containers. Filter evaluation only runs within the maxDepth window — matches deeper than the depth cap are invisible.
COST & LATENCY:
Cost scales with SUBTREE SIZE, not nodeId count. A single PAGE-level id can be as expensive as thousands of leaf ids. Use 'maxDepth' to bound the walk.
Non-safe-list 'fields' trigger per-node exportAsync (moderate cost on retained nodes only). Non-safe-list 'filter' keys trigger exportAsync on EVERY candidate descendant before pruning (higher cost). Prefer safe-list filter keys with tight nodeIds or maxDepth.
MISSING NODES:
ALWAYS check 'missingNodeIds' in the response. Any nodeId not present in 'nodes' is listed there. Treat absence from 'nodes' as authoritative and surface to the user.
RECOMMENDED PAIRINGS:
For cheap structural scans: safe-list filter + no fields.
For targeted property reads: tight nodeIds or maxDepth + specific fields.
For filtered property reads: safe-list filter + fields on retained nodes.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| nodeIds | No | Array of node IDs to get information about. If empty, uses editable scope. | |
| fields | No | Array of field names to return. Supported fields include 'fills', 'strokes', 'cornerRadius', 'opacity', 'blendMode', 'effects', 'characters', 'style', 'layoutMode', 'itemSpacing', 'paddingLeft', 'paddingRight', 'paddingTop', 'paddingBottom', 'primaryAxisAlignItems', 'counterAxisAlignItems', 'absoluteBoundingBox', 'visible', 'locked', 'componentPropertyDefinitions', 'componentProperties', 'overrides', 'transitionNodeID', 'transitionDuration', 'transitionEasing'. | |
| filter | No | Optional filter criteria. Format: { fieldName: [value1, value2] }. Example: { type: ['TEXT', 'COMPONENT'], layoutMode: ['HORIZONTAL'] }. Matches are case-sensitive and multiple values for a field are treated as OR. Multiple fields are treated as AND. | |
| maxDepth | No | Maximum depth for recursive child traversal. 0 = self only, 1 = self and immediate children, etc. If omitted, performs a full depth traversal (use with caution on large subtrees). |