API Reference

Threat Actor CVEs

The CVEs a threat actor is reported to have exploited — each with the quote that attributes it, the source URL, and the severity signals you need to act: CVSS, EPSS, CISA KEV status and Precursor's action priority.

This is the endpoint for the question a security team actually gets asked: "this group is in the news, what should we patch?" Get Actor carries the same claims, but bare. This one joins them to exploitability data and orders by it, in one round trip.

GET

/v1/actors/{name}/cves

Cost: 1 credit per successful call

Path parameters

namestringrequired

Slug, alias, or display name — all three resolve. 1–120 characters, URL-encoded. Examples: safepay, Cozy%20Bear, APT29.

Query parameters

limitintegeroptional

1–200. Defaults to 100.

Request

curl https://api.precursorintelligence.com/functions/v1/actors/safepay/cves \
  -H "Authorization: Bearer $PRECURSOR_API_KEY"

Response

200 OK

{
  "data": {
    "actor": {
      "id": "228233a4-d091-4214-baf7-f10db9aecda4",
      "name": "SafePay",
      "slug": "safepay",
      "query": "safepay",
      "matched_on": "slug"
    },
    "count": 2,
    "total": 2,
    "limit": 100,
    "items": [
      {
        "cve_id": "CVE-2023-27997",
        "relation": "exploited",
        "evidence_quote": "FortiOS SSL VPN Heap Buffer Overflow CVE-2023-27997 Pre-authentication module vulnerability allows remote code execution through heap overflow exploitation",
        "source_url": "https://www.halcyon.ai/threat-group/safepay",
        "cvss_score": 9.8,
        "epss_score": 0.85689,
        "epss_percentile": 0.99695,
        "risk_score": 88,
        "action_priority": "Emergency patch",
        "cisa_kev": {
          "listed": true,
          "date_added": "2023-06-13",
          "due_date": "2023-07-04"
        }
      },
      {
        "cve_id": "CVE-2024-21762",
        "relation": "exploited",
        "evidence_quote": "FortiOS SSL VPN Out-of-Bounds Write CVE-2024-21762 9.8 Enables remote unauthenticated attackers to execute arbitrary code via specially crafted HTTP requests",
        "source_url": "https://www.halcyon.ai/threat-group/safepay",
        "cvss_score": 9.8,
        "epss_score": 0.80835,
        "epss_percentile": 0.99579,
        "risk_score": 90,
        "action_priority": "Emergency patch",
        "cisa_kev": {
          "listed": true,
          "date_added": "2024-02-09",
          "due_date": "2024-02-16"
        }
      }
    ],
    "generated_at": "2026-08-04T10:20:34.843Z"
  },
  "meta": {
    "request_id": "8b16efb8-9a6c-4ace-b817-11cbee626d08",
    "generated_at": "2026-08-04T10:20:34.843Z",
    "credits": { "charged": 1, "remaining": 9998 }
  }
}

Ordering

Results are ordered CISA KEV first, then by EPSS descending, then CVSS descending — the order a remediation queue wants, not the order the claims were ingested.

Response fields

data.actor.matched_onstringoptional

Which identifier resolved the lookup: slug, alias, or name.

data.actor.merged_fromstring | nulloptional

Present only when {name} hit a merged actor's tombstone. Results are the surviving actor's; update your stored identifier to data.actor.slug.

data.totalintegeroptional

Distinct CVEs attributed to this actor before limit. Compare with count to detect truncation.

data.items[].relationstringoptional

How the actor relates to the CVE — exploited, attributed, or uses.

data.items[].evidence_quotestring | nulloptional

The sentence from the source that attributes this CVE to this actor.

data.items[].source_urlstring | nulloptional

Where that quote was published. Cite this, don't assert.

data.items[].epss_scorenumber | nulloptional

EPSS exploit probability, 0–1.

data.items[].risk_scoreinteger | nulloptional

Precursor Risk Score (PRS), 0–100.

data.items[].action_prioritystring | nulloptional

Recommended urgency, e.g. Emergency patch.

data.items[].cisa_kevobjectoptional

listed, plus date_added and due_date when listed.

One CVE per row, strongest citation kept

If several sources attribute the same CVE to the same actor, it appears once with its strongest citation. For every citation on a CVE, call CVE Threat Actors instead.

Absence is not evidence

An empty items array means no ingested source links this actor to any CVE. It does not mean the actor exploits nothing.

Errors

Status	`error`	When
400	`missing_name`, `invalid_name`	The path segment is missing or failed validation.
400	`invalid_limit`	`limit` is non-numeric or outside 1–200.
401	`invalid_authorization`	Missing or malformed `Authorization` header.
401	`unauthorized`	Invalid/revoked key, or IP not allowlisted.
402	`insufficient_credits`	Organisation credit balance is below 1.
404	`not_found`	The path shape is wrong. Free — raised before billing.
405	`method_not_allowed`	Only `GET` and `OPTIONS` are accepted.
500	`internal`	Unexpected server error (credit auto-refunded).

An unknown actor is a 200, not a 404

A well-formed name that matches no actor returns 200 OK with data set to { "error": "not_found", "name": "…" }, and the credit is still charged. Check for data.error before reading data.items.

See Errors for the full error reference.