---
title: "Exploit chatter and threat actor lookup"
method: POST
path: "/v1/metered/threat-actor"
tags: ["Threat intelligence"]
---

# Exploit chatter and threat actor lookup

`POST /v1/metered/threat-actor`

## Request

- Base URL: `https://api.relayshield.net`
- URL: `https://api.relayshield.net/v1/metered/threat-actor`
- Auth: one of:
  - API key in header `X-RS-API-KEY`
  - HTTP bearer

Two actions on one endpoint, selected with `action`.

`exploit-chatter` detects pre-publication CVE proof-of-concept discussion in criminal channels, with EPSS score and CISA KEV status.

`actor-lookup` (the default) resolves a threat actor or malware campaign to its MITRE ATT&CK group, associated malware, and live indicators from RelayShield's corpus.

**Billing.** $0.30 per successful call. Failed calls are never billed. Charged against prepaid credits when the balance covers it, otherwise metered to your card. Threat Intelligence subscribers and AWS Marketplace bundle customers call this at no extra charge.

## Request body

- object: At least one of: `cve_id`, `actor`, `actors`.
  - `action` 'actor-lookup' | 'exploit-chatter': Which lookup to run.
  - `cve_id` string: Required when action is `exploit-chatter`. Format CVE-YYYY-NNNNN, case-insensitive.
  - `actor` string: Actor or campaign name. Used when action is `actor-lookup`.
  - `actors` string[]: Up to 5 actor names, used when `actor` is not supplied.

## Response `200`

Success. `ok` is true and `data` holds the result.

- object
  - `ok` true, required
  - `data` object, required
    - `results` object[]: actor-lookup only. One entry per search term.
      - `term` string: The term searched.
      - `found` boolean: True when indicators or a MITRE group were resolved.
      - `ioc_count` integer: Indicators found across the actor's associated malware.
      - `ioc_breakdown` object: Counts keyed by indicator type.
      - `sources` string[]: Channels the indicators came from.
      - `latest_ioc` string: Most recent sighting timestamp.
      - `mitre` object: MITRE ATT&CK group detail.
        - `group_name` string: Canonical group name.
        - `aliases` string[]: Known aliases.
        - `techniques` string[]: Up to 10 technique IDs.
        - `description` string: Group description, truncated to 300 characters.
      - `associated_malware` string[]: Malware and tool names resolved via MITRE.
      - `sample_iocs` object[]: Up to 5 example indicators.
        - `value` string: Indicator value.
        - `type` string: Indicator type.
        - `malware` string: Malware family.
        - `seen_ts` string: Sighting timestamp.
    - `terms_searched` integer: actor-lookup only. Number of terms processed.
    - `cve_id` string: exploit-chatter only. The uppercased CVE ID.
    - `found` boolean: exploit-chatter only. True when chatter or linked indicators exist.
    - `risk_level` 'HIGH' | 'MEDIUM' | 'LOW': exploit-chatter only. HIGH with chatter, MEDIUM with only linked indicators, otherwise LOW.
    - `chatter_count` integer: exploit-chatter only. Distinct chatter records.
    - `chatter_sources` string[]: exploit-chatter only. Up to 5 source names.
    - `first_seen` string: exploit-chatter only. Earliest chatter timestamp.
    - `ioc_hits` integer: exploit-chatter only. Indicators referencing the CVE.
    - `in_kev` boolean: exploit-chatter only. True when the CVE is in CISA KEV.
    - `epss_score` number: exploit-chatter only. EPSS exploitation probability, 0.0 to 1.0.
    - `kev_date_added` string: exploit-chatter only. Date added to KEV.
    - `note` string: exploit-chatter only. Interpretation of the result.

## Other responses

- `400`: action is `exploit-chatter` and `cve_id` is missing or malformed, or action is `actor-lookup` and neither `actor` nor `actors` was supplied.
- `401`: Missing or invalid API key.
- `402`: No credits and no active subscription. The response carries `topup_url`.
- `405`: Wrong HTTP method. Every endpoint is POST.

---

[API](https://skmtc.dev/relayshield/apis/relayshield-api.md) · [All operations](https://skmtc.dev/relayshield/apis/relayshield-api/llms.txt) · [OpenAPI document](https://skmtc.dev/relayshield/apis/relayshield-api/revisions/4d4721b936dd?raw)