get_model_element

Edit online

Provides flexible model element retrieval with two distinct modes: bulk pagination mode for efficient whole-model traversal and discovery, or single-element mode for detailed inspection of specific elements with owned elements and relationships.

Purpose

In bulk mode, it returns lightweight element summaries with type distribution and optional hierarchy mapping, ideal for model exploration and filtering. In single-element mode, it provides complete element details including metadata, owned elements (with configurable depth), and relationships, perfect for detailed analysis and documentation.

Tags: AM Read Basic

Input parameters


Parameter	Type	Required	Default	Description
`project_id`	string	Yes	-	Project name or UUID
`ref_id`	string	Yes	-	Commit UUID, branch name, or tag name
`element_id`	string	No	"*"	Element UUID or "*" for bulk mode
`include_owned`	boolean	No	false	Include owned elements (single mode)
`include_relationships`	boolean	No	false	Include relationships (single mode)
`owned_depth`	integer	No	1	Depth of owned nesting (1-10)
`exclude_library`	boolean	No	true	Exclude library elements (bulk mode)
`page`	integer	No	1	Page number (bulk mode)
`limit`	integer	No	50	Page size (50-1000, bulk mode)
`include_elements`	boolean	No	false	Include element records
`include_elements_by_type`	boolean	No	false	Group elements by type
`include_hierarchy`	boolean	No	false	Include parent/child mapping
`detail_level`	string	No	"minimal"	"minimal" or "summary"

Output schema

Field	Type	Description
summary.project_id	string	UUID of the project being searched
summary.ref_id	string	Branch or commit ID used for the search
summary.resolved_commit_id	string	Actual commit UUID resolved from the ref_id
summary.total_matches	integer	Total number of elements matching the search criteria
summary.returned_count	integer	Number of elements returned in this response
summary.page	integer	Current page number
summary.limit	integer	Maximum results per page
summary.has_more	boolean	Indicates if more results are available on subsequent pages
summary.next_page	integer	Next page number (only present if has_more is true)
summary.type_distribution	object	Map of element types to their counts in the search results
summary.type_distribution.{type}	integer	Count of elements for each specific type (example, PartUsage: 450)
elements[].elementId	string	Unique identifier for the element
elements[].name	string	Display name of the element
elements[].actual_name	string	Actual declared name of the element in the model
elements[].elementType	string	SysML v2 type of the element (e.g., PartUsage, AttributeUsage)
elements[].qualifiedName	string	Fully qualified name including package hierarchy
elements[].browser_url	string	Clickable URL to view the element in the web browser

Common use cases

Element discovery: Find elements by name or partial name match. For example: Find all elements containing "Power" in their name.
Type-based search: Locate all elements of a specific type. For example: Show me all PartUsage elements in the project.
Model inventory: Generate lists of elements for documentation. For example: List all interfaces in the system.
Quick navigation: Find specific elements to navigate to in the browser. For example: Find the BatteryController element.