Corpus Analytics

These endpoints aggregate across the entities you can see, rather than returning a single entity. They are intended for dashboards and situational awareness surfaces — a threat overview, a triage feed, and origin attribution.

All three respect your security groups: aggregates and counts are computed only over entities you are permitted to read, so two callers with different group memberships will legitimately see different totals.

Base URL: https://apis.threatwinds.com/api/analytics/v1

Common headers

Header	Type	Required	Description
Authorization	string	Optional	Bearer token from an active session. Authentication is optional but improves rate limits.
api-key	string	Optional	API key. Authentication is optional but improves rate limits.
api-secret	string	Optional	API secret. Authentication is optional but improves rate limits.

---

Overview

Returns a situational snapshot of the corpus: totals, malicious share, composition by type, reputation, accuracy and tags, plus a daily ingest timeline.

Endpoint: GET /overview

Query Parameters

Parameter	Type	Required	Default	Description
days	int	No	30	Days of history for the timeline (1–365).

Example

curl -H "Authorization: Bearer $TOKEN" \
  "https://apis.threatwinds.com/api/analytics/v1/overview?days=14"

Response

{
  "total_entities": 129482,
  "malicious_count": 4671,
  "malicious_share": 0.036,
  "tracked_types": 9,
  "by_type": [
    { "key": "ip", "count": 48210 },
    { "key": "domain", "count": 31904 }
  ],
  "by_reputation": [
    { "key": "-1", "count": 3820 },
    { "key": "0", "count": 124811 }
  ],
  "by_accuracy": [
    { "key": "1", "count": 118402 }
  ],
  "top_tags": [
    { "key": "c2", "count": 612 }
  ],
  "timeline": [
    { "timestamp": "2026-07-26T00:00:00.000Z", "count": 312 }
  ],
  "window": { "days": 14, "interval": "day" }
}

malicious_share is malicious_count / total_entities, where malicious means a negative reputation score. Reputation runs -3..+3 and accuracy 0..3.

---

Recent Activity

Returns entities observed within a time window, newest first. This is the triage feed: by default it returns only entities with negative reputation.

Endpoint: GET /recent

Query Parameters

Parameter	Type	Required	Default	Description
hours	int	No	24	Hours of history (1–720).
limit	int	No	50	Maximum entities to return (1–100).
malicious_only	bool	No	true	Restrict to negative reputation. Pass false for all activity.

Example

curl -H "Authorization: Bearer $TOKEN" \
  "https://apis.threatwinds.com/api/analytics/v1/recent?hours=6&limit=25"

Response

{
  "items": [
    {
      "id": "ip-ad0c2ed9a0a9b23822e5907b0d009bcaf8f969db793cd1d94c40e17e0287c04b",
      "type": "ip",
      "value": "203.0.113.10",
      "reputation": -3,
      "reputation_label": "Alarming",
      "accuracy": 1,
      "accuracy_label": "Imprecise",
      "tags": ["c2"],
      "first_seen": "2026-07-27T16:37:50.530Z",
      "last_seen": "2026-07-27T16:37:51.543Z"
    }
  ],
  "window": { "hours": 6, "since": "2026-07-27T13:00:00Z" }
}

---

Attribution

Aggregates entities by geographic and network origin — country, ASN and autonomous system organisation.

Endpoint: GET /attribution

Query Parameters

Parameter	Type	Required	Default	Description
size	int	No	20	Buckets returned per dimension (1–100).
malicious_only	bool	No	true	Restrict to negative reputation.

Example

curl -H "Authorization: Bearer $TOKEN" \
  "https://apis.threatwinds.com/api/analytics/v1/attribution?size=10"

Response

{
  "by_country": [{ "key": "United States", "count": 1840 }],
  "by_asn": [{ "key": "15169", "count": 622 }],
  "by_aso": [{ "key": "GOOGLE-AS-15169", "count": 622 }],
  "malicious_only": true
}

---

Rate Limits

These endpoints aggregate across the whole index, so they share the heavier entity_relations allowance rather than the cheaper entity-details one.

Tier	Requests per minute (each endpoint)
Public / Free	30
Pro	75
Business	150
Business Max	300
Enterprise	300
Enterprise Max	600

Error Codes

Status Code	Description	Possible Cause
401	Unauthorized	Invalid authentication credentials
429	Too Many Requests	Rate limit exceeded for your tier
500	Internal Server Error	Aggregation failed