---
title: "Search"
method: POST
path: "/search"
tags: ["Links"]
---

# Search

`POST /search`

Search validated relationships between entities in the Links graph with category and type filters.

## Request body

- Query — Query
  - `entities` string[], required — Entities for which to search for links. Uses Recorded Future entity IDs.
  - `filters` object — Filters for which links to search for.
    - `sections` string[] — Filters links only from a specific section (available from **Metadata: Sections**), for example only Actors, Tools & TTPs or only Indicators & Detection Rules.
    - `entity_types` string[] — Filters links only of a specific entity type or types. The types of entities are returned by **Metadata: Entities**.
    - `sources` string[] — The API returns technical links (`technical`) and links from Insikt notes (`insikt`). This filter is used to limit the search to only one of the sources.
    - `technical` object — Subfilters which applies specifically to technical links.
      - `timeframe` string — The time frame filter is used when only technical links newer than some date are of interest, e.g. `-30d` for the last 30 days (maximum timeframe is `-90d`).
      - `events` string[] — The events filter is used to limit the search for links to references of a certain event type or types. The different types of events are found in **Metadata: Events**.
      - `connected_entities` string[] — By using the connected entities filter, only technical links which themselves have links to entities specified in this list are returned.
  - `limits` object — Limits on search depth and number of returned entities.
    - `search_scope` 'small' | 'medium' | 'large' — The Links API searches for links in references, which is a performance intensive search. To ensure a fast response and a balance between different sources among events, there are some filters and limits applied.<br/><br/>It would be impractical with an exhaustive search throughout all references from all time. Instead the API looks through the most recent references. References exist in different event types (the different types are available in /metadata/events) and to ensure some balance among sources, a number of references from each event type are selected.<br/><br/>The exact number of references and Insikt notes fetched is controlled by the search_scope parameter:<br/><ul> <li>search_scope: small = 10 references of each event type, 10 Insikt notes</li> <li>search_scope: medium = 50 references of each event type, 50 Insikt notes</li> <li>search_scope: large = 100 references of each event type plus an extra 1000 references which can be of any type, 500 Insikt notes</li> </ul>
    - `per_entity_type` integer — Limits how many entities /(IP, hashes, etc) are returned of each type from technical links and Insikt notes respectively.

## Response `200`

- SearchResponse — Technically validated entity relationships (from sandbox analysis, Insikt Group research). Supports batch queries and filtering by section, entity type, source, timeframe.
  - `data` ResultSet[] — Array of per-entity link results (one entry per queried entity).
    - `entity` object — A Recorded Future entity reference.
      - `type` string — Entity type (e.g., IpAddress, InternetDomainName, Hash, CyberVulnerability, Malware)
      - `id` string — Recorded Future entity ID (e.g., ip:8.8.8.8, idn:example.com, hash:abc123)
      - `name` string — Human-readable entity name
    - `links` LinkedEntity[] — Linked entities with source attribution and risk scores.
      - `type` string — Linked entity type (e.g., type:IpAddress)
      - `id` string — Linked entity ID
      - `name` string — Linked entity name
      - `source` 'technical' | 'insikt' — Link source: technical (sandbox/automated) or insikt (analyst research)
      - `section` string — Link section ID (use Links Metadata Sections to decode)
      - `attributes` union[] — Risk attributes for the linked entity.
        - 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 Object
      - `Source` string — The application or component that generated this error.
      - `ReasonCode` string — Reason code is a unique constant identifying the error case encountered during request processing.
      - `Description` string — Human-readable short description of the reasonCode
      - `Recoverable` boolean — Recoverable flag indicates whether this error is always returned for this request, or retrying could change the outcome. For example, 'true' or 'false'.
      - `Details` string, nullable — Optional detailed description provides information about data received and calculated during request processing. This helps the user to diagnose errors.

## Other responses

- `400` — Bad request

---

[API](https://skmtc.net/recordedfuture/apis/alert-api.md) · [All operations](https://skmtc.net/recordedfuture/apis/alert-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/recordedfuture/alert-api/revisions/c8c2f68d8b60/schema)