Relationships & pagination

Relationships & pagination

Your key must have relationship access enabled for +relations and relationship endpoints. Otherwise, use view=full for IOC details.

Replace each placeholder with the value for your request:

Relationship queries accept cursor, limit and view. Choose a relationship supported by the source indicator type below. Start with limit=10; for initial integrations, keep pages at 50 or fewer and contact us before requesting larger pages.

Including relationships or increasing the requested limit may use more credits, even when fewer items are returned. Charges depend on your access plan.

Basic and Pro both support relationship queries when relationship access is enabled. Available relationship types and fields depend on the source indicator, response view and account permissions; contact us to discuss specific data requirements. API trial to explore the options.

Not every relation applies to every IOC or permission level. A supported relation may have no items; an unsupported relation can return 404. Follow the returned next_cursor while has_next is true. Keep the IOC, relation, view and other filters unchanged while paging. Treat the cursor as opaque.

curl --get "https://api.virussign.com/v1/ioc/files/YOUR_SHA256/related_domains" \
  --header "x-api-key: $VIRUSSIGN_API_KEY" \
  --data-urlencode "limit=10"

import os
import requests

endpoint = "https://api.virussign.com/v1/ioc/files/YOUR_SHA256/related_domains"
params = {"view": "compact", "limit": 10}
seen_cursors = set()
with requests.Session() as session:
    session.headers["x-api-key"] = os.environ["VIRUSSIGN_API_KEY"]
    for _ in range(10):  # Explicit evaluation page budget.
        response = session.get(endpoint, params=params, timeout=(5, 30))
        response.raise_for_status()
        page = response.json()
        for item in page.get("items", []):
            print(item)  # Replace with idempotent processing.
        if not page.get("has_next"):
            break
        cursor = page.get("next_cursor")
        if not cursor or cursor in seen_cursors:
            raise RuntimeError("Missing or repeated pagination cursor")
        seen_cursors.add(cursor)
        params["cursor"] = cursor
        # Persist this cursor only after processing the page.
    else:
        print("Page budget reached; save the cursor before continuing.")

Record your checkpoint only after successfully processing a page. Make ingestion idempotent so that retrying a page does not create duplicate records. Embedded relationship lists in a detail response can be truncated; use standalone paging for additional results. Website display counts do not cap API results; API page-size limits, permissions and credits still apply.

Relationship response

Embedded relationship page

WHOIS records

Certificate records

Resolution records

Illustrative response

Illustrative data showing the response structure. Optional fields may be omitted.

{
  "meta": {
    "request_id": "example-request",
    "timestamp": "2026-01-15T12:00:00Z",
    "quota_remaining": 100,
    "took_ms": 12
  },
  "returned": 1,
  "has_next": false,
  "items": [
    {
      "type": "domain",
      "value": "beacon.example",
      "analysis": {
        "status": "assessed",
        "malicious": true,
        "detections": 10,
        "crowd_rate": 5
      },
      "context": {
        "relationship": "related_domains"
      }
    }
  ]
}