Skip to main content
Relationship responses help agents discover pivots. Treat them as connected context, then validate important claims with evidence.

​
Response Envelope

/v2/relationships returns: Batch relationship responses use the standard batch envelope described in Batch responses.

​
General relationship pagination

For general actor, malware, IOC, and other existing pivots, relationship pagination uses opaque snapshot cursors. When next_cursor is present, pass it back unchanged with the same request inputs to retrieve the next slice of the original ranked result set. Do not parse or modify the cursor. For unchanged request inputs, paged traversal is page-size invariant: requesting two pages of five items returns the same ordered set as requesting one page of ten items, subject to cursor expiry. Relationship cursors expire after 10 minutes and are retained in cache longer so clients can distinguish an expired cursor from a cursor that cannot be found. max_results controls page size and is capped at 100. Each traversal snapshot contains up to 500 ranked results, which allows up to five full pages from a single snapshot. A request path that attempts to continue beyond the bounded snapshot, such as a sixth 100-result page, is not covered by the stable-result guarantee.

​
ATT&CK relationship responses

ATT&CK items use relationship_type and target_entity_type for the related entity type. predicate gives the link meaning, and direction is incoming or outgoing relative to your subject. ATT&CK score is currently 1.0 for a matched link, not a threat likelihood or detection effectiveness estimate. evidence_count counts link provenance references; it does not count observed procedure executions. A no_relationships result means no links matched this request in the available dataset, not that a behavior is undetectable. ATT&CK pagination uses deterministic ordering and cursors bound to the resolved subject, filters, context, and result snapshot. Pass next_cursor unchanged as cursor. If the request or snapshot changes, the API returns HTTP 400; restart without the cursor. The general traversal’s ten-minute expiry and 500-result snapshot rules above do not apply to ATT&CK cursors. max_results remains 1–100. An ATT&CK catalog exceeding the supported retrieval bound returns HTTP 503 instead of a silently incomplete traversal. See the ATT&CK workflow for predicates, filters, and a PowerShell example.

​
Key fields

Relationship items may include:
  • related entity ID and name
  • relationship type
  • direction or role
  • confidence
  • supporting evidence references
  • pagination cursor fields

​
IOC Relationship Expansion

For IOC subjects (ip, domain, url, hash, or email), relationship_types: ["ioc"] returns related indicators from event-correlation context when available. This is the supported path for IOC expansion; /v2/ioc-assessments does not return correlated IOCs inline. IOC subjects can also return sector relationships for targeted industries and country relationships for targeted countries when that context is available. These pivots are useful for environment relevance, especially when they match a caller-provided sector or operating region. IOC relationship items use relationship_type: "ioc", target_entity_type: "ioc", and include metadata.indicator_type when known. Sector and country relationship items use matching relationship_type and target_entity_type values. Treat all relationship items as pivots for hunting or blocking review, not proof by themselves.

​
How to use Relationships

Use relationships to select the next investigation step:
  • Actor links can trigger actor assessments.
  • Malware links can trigger malware or generic threat assessment paths.
  • IOC links can trigger IOC assessment or blocking review.
  • Sector links can support industry relevance.
  • Country links can support geography relevance.
  • Technique links can guide detection and hunting.

​
Caveat

Do not treat a relationship by itself as proof of current exploitation or targeting. Validate high-impact links with evidence.