Find elements
find_elementsFind project elements using combinable filters like type, story, layer, or region, and get a paginated list with GUIDs, IDs, and layer data. All filters AND-combine.
Instructions
Finds elements in the open project with combinable filters (type, story, layer, renovation status, visibility/editability, selection, Element ID pattern, library part name, group, hotlink, lock state, spatial region) and returns a paginated list [{guid, type, storyIndex, layer: {index, name}, elementId, boundingBox?, libraryPart?}] plus total/hasMore. All filters are optional and AND-combined; with no filter every main element is listed. Use the GUIDs with get_element_details, get_element_quantities, modify_elements, set_selection etc. For counts only use get_element_counts. Coordinates in meters.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Return at most this many matches. Default 500 | |
| types | No | Only these element types. Default: every main type (sub-elements such as curtain wall panels, stair treads or railing posts are only included when listed here or with includeSubelements=true) | |
| layers | No | Only elements on these layers (layer names are localized, e.g. Russian — take them from get_attributes or earlier results) | |
| locked | No | true = only locked elements, false = only unlocked ones | |
| offset | No | Skip this many matches (pagination). Default 0 | |
| region | No | Spatial filter on the element's 3D bounding box (2D elements have a flat box at z=0). Give any subset of the limits; e.g. {xMin:0, yMin:0, xMax:10, yMax:8} for a plan rectangle | |
| filters | No | Archicad visibility/editability filters; an element must pass ALL of them | |
| grouped | No | true = only grouped elements, false = only ungrouped ones | |
| stories | No | Only elements whose home story is one of these | |
| elementId | No | Element ID (the ID shown in the Info Box) wildcard pattern, case-insensitive: '*' = any characters, '?' = one character; without wildcards the ID must match exactly. Examples: 'W-*', '*01', 'D-0??' | |
| groupGuid | No | Only members of this group (nested groups included); groupGuid comes from get_element_details | |
| inHotlink | No | true = only elements that come from a hotlinked module, false = only own elements | |
| storyIndex | No | Only elements whose HOME story is this one (index or localized name, see get_stories) | |
| hotlinkGuid | No | Only elements belonging to this hotlink instance | |
| libraryPart | No | Library part name contains this text (case-insensitive). Applies to objects, lamps, windows, doors, skylights and zone stamps; other types are excluded. Names are localized | |
| excludeTypes | No | Skip these element types | |
| selectedOnly | No | Only elements in the current selection | |
| withinElements | No | Restrict the search to these elements (e.g. to refine an earlier result) | |
| includeElementId | No | Include the Element ID string. Default true | |
| renovationStatus | No | Only elements with one of these renovation statuses | |
| includeBoundingBox | No | Add boundingBox {xMin,yMin,zMin,xMax,yMax,zMax} (m, z absolute) to each element. Default false | |
| includeLibraryPart | No | Add the library part name of objects/lamps/doors/windows/skylights/zones. Default false | |
| includeSubelements | No | Also list sub-elements (curtain wall/stair/railing parts, beam/column segments) when 'types' is not given, and the hidden GDL part Objects/Lamps owned by curtain walls, railings and stairs (skipped otherwise, counted in stats.ownedPartObjectsSkipped). Default false |