--- title: "Search for links" method: POST path: "/search" tags: ["Links"] --- # Search for links `POST /search` ## Request - Base URL: `https://api.recordedfuture.com/links` - URL: `https://api.recordedfuture.com/links/search` - Auth: one of: - API key in header `X-RFToken` - OAuth 2 - Authorization code: `https://id.recordedfuture.com/authorize` - Token URL: `https://id.recordedfuture.com/token` Search for validated relationships between entities in the Links graph. Links represent technically validated relationships between entities — established through sandbox analysis, infrastructure analysis, network traffic analysis, and Insikt Group research — not mere co-occurrence in articles. The Entity Match API may be used to determine the ID for a certain entity. For quick single-entity triage, the `links` enrichment field on entity Lookup endpoints provides the same intelligence in a more compact format combined with other enrichment. Use this dedicated Links API instead when you need filtering, batch queries across multiple entities, per-entity risk scores on linked entities, or graph traversal via the `connected_entities` filter. **Filters** This endpoint supports a variety of filters that can be used to control either the output or the sources used. In order to filter the output, _sections_ may be used to only return links categorized as for example "Victims & Exploit Targets", or _entity_types_ to only return certain types of entities, like IP addresses. See the metadata endpoint for possible values. Sources are grouped into two types, technical analysis and Insikt Group research. Technical link sources may be further filtered by specifying only the relevant event types, or a timeframe for event recency (up to a maximum of 1825 days from today). **Limits** The depth of the search is abstracted into defined _scopes_. A larger scope _may_ yield more links, at the cost of increased latency. See the `search_scope` filter for the exact number of references searched per scope. A maximum number of results per entity type may also be defined. **Results** Results are grouped on the input entity ID, and may include an _error_ property if the search for that particular entity failed. Linked entities are always returned with a basic set of properties as well as a variable set of attributes that depend on the entity type. For example, indicators will have risk data, MITRE ATT&CK identifiers will have a more detailed name and organizations, companies and persons will have a boolean flag for whether or not they are threat actors. ## Request body - Query: Query - `entities` string[], required: IDs of entities to return links for. If more than one ID is provided, it is equivalent of calling this endpoint once for each, condensed into one call. - `filters` object: Filters the result based on link characteristics and the source of the link. - `sections` string[]: Filters links to only a specific section (available from Metadata: Sections), for example only "Actors, Tools & TTPs" or only "Indicators & Detection Rules". - `entity_types` string[]: Filters links to only a specific entity type or types. The types of entities are returned by Metadata: Entities. - `sources` string[]: Limits the search to only one source type: technical links, or links from Insikt notes. - `technical` object: Filtering options specific to links from technical sources. - `timeframe` string: Time range for links from technical sources. As an ISO Date (2022-01-01) or relative to today (-7d). Maximum of 1825 days from today. - `events` string[]: Limits the search for links to references of a certain event type or types. The available event types are returned by Metadata: Events. - `connected_entities` string[]: Only returns technical links that themselves have links to entities specified in this list. - `limits` object - `search_scope` 'small' | 'medium' | 'large': Predefined levels of search depth. A larger scope may yield more linked entities, at the cost of increased latency. The scope controls how many references are searched per technical event type, and how many Insikt notes are searched: small = 10 references of each event type, 10 Insikt notes; medium = 50 references of each event type, 50 Insikt notes; large = 100 references of each event type plus an extra 1000 references of any type, 500 Insikt notes. - `per_entity_type` integer: The maximum number of returned entities per type (IP, hash, etc), applied separately to entities found via technical links and via Insikt notes. Indicators are sorted by risk prior to filtering. ## Response `200` - SearchResponse: The result of a links query - `data` ResultSet: The result of a link query. - `entity` object - `type` string: Type of the input entity - `id` string: ID of the input entity - `name` string: Name of the input entity - `links` LinkedEntity[] - `type` string: The type of the entity - `id` string: Internal ID of the entity - `name` string: Human readable name of the entity - `source` 'technical' | 'insikt': The source of the link between entities - `section` string: The section or category of the link - `attributes` union[]: A variable list of attributes that depends on the entity type. IoCs (like IpAddress and Hash) should always have risk and criticality related attributes, MitreAttackIdentifiers will have a display name with more details and organizations, companies and persons will have a "threat actor" boolean flag. If "threat actor" is false, risk data may also be included. - union - object - `id` 'risk_score' | 'risk_level' - `value` integer - object - `id` 'criticality' - `value` string - object - `id` 'display_name' - `value` string - object - `id` 'threat_actor' - `value` boolean - `error` Error: Error information if the link search for an entity failed for some reason. - `message` string - `status_code` integer ## Other responses - `400`: Bad request --- [API](https://skmtc.dev/recordedfuture/apis/links-api.md) - [All operations](https://skmtc.dev/recordedfuture/apis/links-api/llms.txt) - [OpenAPI document](https://skmtc.dev/recordedfuture/apis/links-api/revisions/b8743c2f0df1?raw)