Search hierarchy labels in a hierarchy instance

Learn more about how to use the search hierarchy label API to return matching entries and their paths in a hierarchy instance.

Use the Search Hierarchy label to search for objects by label in a hierarchy instance. This operation requires the MDM.Data.Hierarchy permission with the READ privilege.

HTTP method and endpoint

Use the following HTTP method and endpoint path to submit the request:

GET https://<environment>.reltio.com/reltio/api/{tenantId}/hierarchies/{instanceId}/labelSearch

Request headers

The following request headers must be included.


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

Query parameters

The following table describes the query parameters and their values.


Parameter	Type	Required	Description	Accepted values / Default
`query`	String	Yes	The input string used to search hierarchy labels.	Minimum 3 characters, maximum 100 characters. Example: `Labe`
`date`	String	No	Returns the hierarchy state for a specific date. Use ISO 8601 date format.	Example: `2025-10-10`. Default: today

Request body

This operation does not require a request body.

Example request

Use the following example to see how a complete request is structured with headers.

GET /{instanceId}/labelSearch?query=Labe&date=2025-10-10
Authorization: Bearer <token>

Response fields

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


Field	Type	Description
`entityId`	String	The entity ID of the matched object.
`labels`	Array of strings	The path labels for the matched entry. One random path is chosen. The matched entity is always the last item in the list.

Example response

The following example shows the response body.

[
  {
    "entityId": "matchedId1",
    "labels": [
      "Root",
      "Level 1 object",
      "Level 2.1 object",
      "Matched entity 1"
    ]
  },
  {
    "entityId": "matchedId2",
    "labels": [
      "Root",
      "Level 1 object",
      "Level 2.2 object",
      "Matched entity 2"
    ]
  }
]

Unify and manage your data