Get Hops

Learn how to retrieve entities and relationships by traversing connected records using N-hop logic.

There is a limit of 1,500 entities that can be returned per API call.

Request

GET {TenantURL}/entities/{entity object URI}/_hops

Table 1. Parameters
Parameter		Required	Description
Headers	`Authorization`	Yes	Information about authentication access token in format "Bearer `<accessToken>`" (see details in Authentication API).
Query	`select`	No	Comma-separated list of properties from the entity structure that should be returned in a response. Allows you to return a partial object. This parameter can be used to include the following fields: entity label (using the `label` keyword) entity secondaryLabel (using the `secondaryLabel` keyword) entity or relation attributes (prefixing `entities` or `relations` before the `attributes` keyword) Note: The `select` parameter supports all attributes. The following query returns data for all fields: `select=label,secondaryLabel,entities.attributes,relations.attributes` Note: Data is also returned for all fields if the `select` parameter is not used in the request.
	`graphTypeURIs`	No	Comma-separated list of graph types URIs for graphs to be traversed. For more information, see Select a graph type .
	`relationTypeURIs`	No	Comma-separated list of relation type URIs (see details in Relation Types) for relation to be traversed.
	`entityTypeURIs`	No	Comma-separated list of entity type URIs (see details in Entity Types) for relation to be traversed.
	`deep`	No	Limits traversing deep levels. Default is `1`.
	`max`	No	Limits the amount of entities to be returned from the API. If the number of entities does not fit into the specified level, then only entities from previous levels are returned.
	`activeness_enabled`	No	Flag to determine whether to return only active entities and relations. If set to `false`, the response includes both active and inactive entities and relations, regardless of their `endDate` values. Default is `true`.
	`filterLastLevel`	No	Flag to NOT count relationships from the last level of deep to the next level after the last. In a response it affects these entity parameters: `untraversedRelationsCount` and `traversedRelationsCount`. Default is `true`.
	`returnDataAnyway`	No	Flag that allows the API to return partial data when used with `limitCreditConsumption=true`. If the request exceeds the credit consumption limit, the response includes all retrieved data along with the `dataComplete=false` flag. Default is `false`.
	`options`	No	Comma-separated list of options that affect the structure of entities in the response. Available options: `sendHidden`: Disabled by default. Includes hidden attributes in the entity JSON if enabled. `ovOnly`: Returns only attribute values where `ov=true`. `nonOvOnly`: Returns only attribute values where `ov=false`. If a nested or reference attribute has `ov=true` but contains sub-attributes with `ov=false`, those sub-attributes won’t appear in the response. `sendMasked`: Returns masked attribute values if masking is configured in the L2 or L3 configuration. `showAppliedSurvivorshipRules`: Returns the survivorship determination logic used to determine the OV value of an attribute, down to the lowest level for each attribute and each value of an attribute. When you use `showAppliedSurvivorshipRules`, the `ovDetails` section has the following fields: `appliedSurvivorshipRules` (legacy): Contains the applied survivorship strategy and fallback information. This legacy response format is retained for backward compatibility. `appliedSurvivorshipRuleTree` (recommended): Provides a more detailed version of the applied survivorship strategy and fallback strategies, including source ordering information where applicable. The following response fields are supported: `appliedSurvivorshipRule`: Name of the survivorship strategy applied at the current level. `sourcesUriOrder`: Ordered list of source URIs for an `SRC_SYS` strategy. This field is omitted for other strategies and when `sourcesUriOrderDerivedFrom` is `none`. `sourcesUriOrderDerivedFrom`: Indicates how `sourcesUriOrder` was derived for an `SRC_SYS` strategy. The following values are supported: `mapping`: The source order is configured at the mapping level. The API returns the `sourcesUriOrder` value from the L3 mapping configuration. `group`: The source order is configured at the group level. The API returns the `sourcesUriOrder` value from the L3 group configuration. `priority`: The source order is derived from sources associated with the attribute that have an L3 priority. The API returns the sources in descending priority order. `none`: No priority or source order is configured, or no applicable source order is found. The response omits `sourcesUriOrder`. `fallbacks`: List of fallback strategies. Each fallback contains `appliedSurvivorshipRule` and `fallbacks`. An `SRC_SYS` fallback also includes `sourcesUriOrderDerivedFrom` and, where applicable, `sourcesUriOrder`. A sample response is given below: `{ "ovDetails": { "appliedSurvivorshipRules": { "SRC_SYS": [ "MinValue" ] }, "appliedSurvivorshipRuleTree": { "appliedSurvivorshipRule": "SRC_SYS", "sourcesUriOrder": [ "configuration/sources/SRC1", "configuration/sources/SRC2" ], "sourcesUriOrderDerivedFrom": "mapping", "fallbacks": [ { "appliedSurvivorshipRule": "MinValue", "fallbacks": [] } ] }, "appliedSurvivorshipGroup": "GroupA", "participationStatus": "strategy" } }` Note: The new `ovParticipationStatus` property indicates how an attribute value participates in OV calculation. It explicitly represents values that are excluded or handled differently during OV processing. This property supports the following enum values: `ignored`, `pinned`, `end-dated-crosswalk`, `not-participated`, and `strategy`. `explainOv`: returns additional survivorship diagnostics in the `ovDetails` section, including matched and unmatched filters as defined in the business configuration. It includes the following root-level and rule-level fields: `appliedSurvivorshipGroup`: Applied survivorship group for the attribute value. `participationStatus`: Indicates how the attribute value participates in OV calculation. `matchedFilters`: Filters from the business configuration that matched during survivorship evaluation. `unmatchedFilters`: Filters from the business configuration that did not match during survivorship evaluation. `winnerCrosswalks`: Final list of winner crosswalks for the OV value. Each object contains `type`, which identifies the source type URI, and `value`, which identifies the crosswalk value. `appliedSurvivorshipRule`: The survivorship rule applied at the current level. `sourcesUriOrder`: Displays an ordered list of source URIs for an `SRC_SYS` strategy. This field is omitted for other strategies and when `sourcesUriOrderDerivedFrom` is `none`. `sourcesUriOrderDerivedFrom`: Indicates how `sourcesUriOrder` was derived for an `SRC_SYS` strategy. The following values are supported: `mapping`: The source order is configured at the mapping level. The API returns the `sourcesUriOrder` value from the L3 mapping configuration. `group`: The source order is configured at the group level. The API returns the `sourcesUriOrder` value from the L3 group configuration. `priority`: The source order is derived from sources associated with the attribute that have an L3 priority. The API returns the sources in descending priority order. `none`: No priority or source order is configured, or no applicable source order is found. The response omits `sourcesUriOrder`. `winningCrosswalks`: Winner crosswalks returned by the rule applied at the current level. `sourcesForOv`: Reference to the `sourcesForOv` setting from the business configuration for the current rule. `fallbackCriteria`: Reference to the fallback criteria from the business configuration. Supported values are `ZERO`, `ZERO_OR_MORE_THAN_ONE`, and `MORE_THAN_ONE`. `fallbacks`: List of fallback rules. Each fallback contains the same fields as the parent rule: `appliedSurvivorshipRule`, `winningCrosswalks`, `sourcesForOv`, `fallbackCriteria`, and `fallbacks`. An `SRC_SYS` fallback also includes `sourcesUriOrderDerivedFrom` and, where applicable, `sourcesUriOrder`. A sample response is given below: { "ovDetails": { "winnerCrosswalks": [ { "type": "configuration/sources/LNKD", "value": "LNKD_RANK" } ], "appliedSurvivorshipGroup": "default", "participationStatus": "strategy", "unmatchedFilters": [ { "and": [ { "uri": "configuration/entityTypes/HCO/attributes/MultipleFilters", "value": "matchedValue", "operator": "ne" } ] } ], "appliedSurvivorshipRules": { "appliedSurvivorshipRule": "SRC_SYS", "sourcesUriOrder": [ "configuration/sources/LNKD", "configuration/sources/SRC2" ], "sourcesUriOrderDerivedFrom": "mapping", "fallbacks": [ { "appliedSurvivorshipRule": "MinValue", "fallbacks": [], "fallbackCriteria": "MORE_THAN_ONE", "winningCrosswalks": [ { "type": "configuration/sources/LNKD", "value": "LNKD_RANK" } ], "sourcesForOv": [ "configuration/sources/LNKD" ] } ], "fallbackCriteria": "MORE_THAN_ONE", "winningCrosswalks": [ { "type": "configuration/sources/LNKD", "value": "LNKD_RANK" } ], "sourcesForOv": [ "configuration/sources/LNKD" ] }, "matchedFilters": [ { "and": [ { "uri": "configuration/entityTypes/HCO/attributes/MultipleFilters", "value": "unmatchedValue", "operator": "ne" } ] }, { "equals": [ { "uri": "configuration/entityTypes/HCO/attributes/MultipleFilters", "value": "matchedValue" } ] } ] } }

Response

Collections of traversed entities and relations with default details:

Relations:
- uri: URI of a relation.
- type: type of a relation.
- attributes: attributes of a relation. It can be displayed or excluded using the select parameter.
- startObject: contains information about the start object URI, and the directionalLabel object.
- endObject: contains information about the end object URI, and the directionalLabel object.
- startDate: relation start date, if available.
- endDate: relation end date, if available.
- direction: direction of a relation, if available.
- crosswalks: crosswalks of a relation.
- consolidatedRating: consolidated rating of a relation, if available.
Entities:
- uri: URI of an entity that is traversed.
- type: type of an entity.
- label: label of an entity. It can be displayed or excluded using the select parameter.
- secondaryLabel: secondary label of an entity. It can be displayed or excluded using the select parameter.
- attributes: attributes of an entity. It can be displayed or excluded using the select parameter.
- traversedRelationsCount: number of relations of an entity that were traversed with this operation.
- untraversedRelationsCount: number of relations of an entity that were not traversed with this operation.
- startDate: entity start date, if available.
- endDate: entity end date, if available.

Consider this graph:

Request 1

GET {TenantURL}/entities/1/_hops?select=entities.attributes.Gender&max=5&deep=1Headers:
                Authorization: Bearer {your-access-token}

Response 1

{
	"relations": [{
		"URI": "relations/1_2",
		"type": "configuration/relationTypes/Parent",
		"startObject": {
			"objectURI": "entities/1",
			"directionalLabel": "mother"
		},
		"endObject": {
			"objectURI": "entities/2",
			"directionalLabel": "daughter"
		},
		"direction": "directed"
	}, {
		"URI": "relations/1_3",
		"type": "configuration/relationTypes/Parent",
		"startObject": {
			"objectURI": "entities/1",
			"directionalLabel": "mother"
		},
		"endObject": {
			"objectURI": "entities/3",
			"directionalLabel": "son"
		},
		"direction": "directed"
	}, {
		"URI": "relations/2_3",
		"type": "configuration/relationTypes/Sibling",
		"startObject": {
			"objectURI": "entities/2",
			"directionalLabel": "sister"
		},
		"endObject": {
			"objectURI": "entities/3",
			"directionalLabel": "brother"
		},
		"direction": "undirected"
	}],
	"entities": [{
		"URI": "entities/1",
		"type": "configuration/entityTypes/Individual",
		"label": "Ann Roman",
		"untraversedRelationsCount": 0,
		"traversedRelationsCount": 2,
		"attributes": {
			"Gender": [{
				"value": "Female"
			}]
		}
	}, {
		"URI": "entities/2",
		"type": "configuration/entityTypes/Individual",
		"label": "Marsha Smith",
		"untraversedRelationsCount": 0,
		"traversedRelationsCount": 2,
		"attributes": {
			"Gender": [{
				"value": "Female"
			}]
		}
	}, {
		"URI": "entities/3",
		"type": "configuration/entityTypes/Individual",
		"label": "John Roman",
		"untraversedRelationsCount": 0,
		"traversedRelationsCount": 2,
		"attributes": {
			"Gender": [{
				"value": "Male"
			}]
		}
	}],
    "dataComplete": true  
}

Request 2

GET {TenantURL}/entities/1/_hops?max=2&deep=1Headers: Authorization: Bearer
                {your-access-token}

Response 2

{
	"relations": [],
	"entities": [{
		"URI": "entities/1",
		"type": "configuration/entityTypes/Individual",
		"label": "Ann Roman",
		"untraversedRelationsCount": 2,
		"traversedRelationsCount": 0
	}],
    "dataComplete": true
}

Unify and manage your data

Get Hops

Footer