API Reference

List Top Malware Families

Return the most-referenced malware families across intelligence reporting, ranked by mention count.

GET

/v1/malware/top

Cost: 1 credit per successful call

Query parameters

limitintegeroptionaldefault: 10

Maximum number of malware families to return. Accepted range: 1–50.

Request

curl "https://api.precursorintelligence.com/functions/v1/malware/top?limit=15" \
  -H "Authorization: Bearer $PRECURSOR_API_KEY"

Response

200 OK

{
  "data": {
    "count": 15,
    "items": [
      { "family": "Cobalt Strike", "mention_count": 412, "first_blogged": "2014-03-01" },
      { "family": "QakBot",        "mention_count": 287, "first_blogged": "2008-09-15" },
      { "family": "Emotet",        "mention_count": 261, "first_blogged": "2014-06-10" }
    ],
    "generated_at": "2026-05-18T10:24:31.118Z"
  },
  "meta": {
    "request_id": "8b16efb8-9a6c-4ace-b817-11cbee626d08",
    "generated_at": "2026-05-18T10:24:31.118Z",
    "credits": { "charged": 1, "remaining": 9998 }
  }
}

Response fields

data.countintegeroptional

Number of malware families returned (equals items.length).

data.itemsarrayoptional

Malware families ranked by mention count, descending. Each object contains the fields below.

data.items[].familystringoptional

Malware family name.

data.items[].mention_countintegeroptional

Number of times the family is referenced across intelligence reporting.

data.items[].first_bloggedstringoptional

ISO 8601 date the family was first mentioned in reporting.

data.generated_atstringoptional

ISO 8601 timestamp indicating when this response was generated.

Errors

Status	`error`	When
400	`invalid_limit`	`limit` is outside the range 1–50.
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 route or entity does not exist.
405	`method_not_allowed`	Only `GET` and `OPTIONS` are accepted.
500	`internal`	Unexpected server error (credit auto-refunded).

See Errors for the full error reference.