Get Tree

Learn about how this API returns a tree of entities built on specified graph type relations.

Use Get Tree to return a tree of entities built on specified graph type relations.

This request returns a tree that includes the initial entity, the entity's parent, all the parent's children, the parent's parent with all its children, and so on until the last parent in the tree. Each node also contains the number of child elements inside it.

In the case of an entity that has several parents, the parent attribute in the response is an array of URIs, and the relation attribute is an array of relations.

CAUTION: Use the _tree request with caution. This request always reads several graph levels to define the tree and can consume significant platform resources. For large hierarchies, the response can take several minutes. In reversed hierarchies with multiple parent paths, the response still returns a single root branch, and the selected root branch is not guaranteed to be the same for every request.

HTTP method and endpoint

Use the following HTTP method and endpoint path to submit the request to return a tree for the specified entity.

GET {TenantURL}/{entity object URI}/_tree

Endpoint path parameters

The following table describes the endpoint path parameters.


Parameter	Type	Required	Description
`{entity object URI}`	String	Yes	The URI of the entity used as the starting point for the returned tree.

Query parameters

The following table describes the query parameters and their values. A query parameter is a key-value pair added to the end of a URL to modify or refine a request.


Parameter	Type	Required	Description	Accepted values / Default
`graphTypeURIs`	String	Yes	Comma-separated list of graph type URIs for graphs to be traversed.	Comma-separated list of graph type URIs.
`select`	String	No	Comma-separated list of properties from the object structure that should be returned in the response. This parameter allows you to return a partial object. It can be used to include the entity label by using `label`, the entity secondary label by using `secondaryLabel`, and entity attributes by prefixing `entities` before the `attributes` keyword.	Example: `select=label,secondaryLabel,entities.attributes`. If not specified, data is returned for all fields.
`options`	String	No	Comma-separated list of options that affect entity JSON content in the response.	Available values: `sendHidden` - includes hidden attributes. `ovOnly` - returns only attribute values with `ov=true`. `nonOvOnly` - returns only attribute values with `ov=false`. `reverseRelations` - returns the hierarchy with reversed directions of all relations. When `reverseRelations` is used, the response still returns a tree with a single root. If the reversed hierarchy produces multiple possible root branches, the response includes one fully expanded root branch and represents the other parent connections by URI references in the `parent` field.

Request headers

The following request headers must be included.


Header	Value	Required
`Authorization`	Bearer `<accessToken>`	Yes

For more information, see Authentication API.

Response body

The following table describes the fields returned in the response body.


Parameter	Type	Description
`success`	Boolean or String	Indicates whether the request succeeded.
`root`	Object	Root node of the returned tree.
`entity`	Object	Entity content, including label, secondary label, and attributes when requested.
`total`	Number	Number of child elements inside the node.
`children`	Array	Child nodes of the current node.
`relation`	Object or Array	Relation content that connects the entity with its parent. For an entity with several parents, this field is an array of relations.
`parent`	String or Array	URI of the parent entity. For an entity with several parents, this field is an array of parent URIs.

Example response

The following example shows the format of a successful response.

{
    "success": "true",
    "root": {
        "entity": "entity content, including label/secondaryLabel, attributes",
        "total": 50,
        "children": [{
                "entity": "entity content, including label/secondaryLabel, attributes",
                "relation": "relation content which connects the entity with its parent",
                "parent": "URI of parent entity",
                "total": 0
            },
            {
                "entity": "entity content, including label/secondaryLabel, attributes",
                "relation": "relation content which connects the entity with its parent",
                "parent": "URI of parent entity",
                "total": 5,
                "children": [
                    ...
                ]
            },
            ....
        ]
    }
}

Unify and manage your data