Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/webhood-io/webhood/llms.txt

Use this file to discover all available pages before exploring further.

The Network Trace endpoint serves a structured JSON file that records every HTTP request and response observed by the headless browser during a completed scan. The trace covers the full request lifecycle — including redirects, subresource loading, and failed requests — giving analysts a detailed picture of a page’s network behavior. This is particularly valuable for detecting redirect chains leading to phishing infrastructure, identifying external resource loading from suspicious domains, and flagging unexpected POST requests that exfiltrate data. The trace is stored as html[1] in the scan record and follows the Traces schema version 0.1.

Request

GET /api/v1/scans/:id/trace

Authentication

All requests require a valid Bearer token in the Authorization header.
Authorization: Bearer <token>

Path Parameters

id
string
required
The unique identifier of the scan record whose network trace you want to download. Must correspond to a scan with status of done.

Response

Returns a JSON object matching the Traces schema. The Content-Type is application/json.

Response Fields

version
string
Trace format version. Currently always "0.1".
traces
array
Array of TraceWrap objects, one per observed request event, in the order they were captured.

Examples

Download and Save the Trace

curl http://localhost:8000/api/v1/scans/a1b2c3d4e5f6g7h8/trace \
  -H 'Authorization: Bearer <token>' \
  --output trace.json

Sample Trace JSON (Abbreviated)

{
  "version": "0.1",
  "traces": [
    {
      "type": "requestfinished",
      "request": {
        "type": "request",
        "url": "http://suspicious-login.net/verify",
        "ts": 1714001210000,
        "headers": {
          "user-agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
          "accept": "text/html,application/xhtml+xml"
        },
        "method": "GET",
        "resourceType": "document",
        "redirectChain": [],
        "postData": ""
      },
      "response": {
        "type": "response",
        "url": "https://phishing-redirect.example/login",
        "ts": 1714001210420,
        "status": 301,
        "headers": {
          "location": "https://phishing-redirect.example/login",
          "server": "nginx/1.18.0"
        },
        "remoteAddress": {
          "ip": "198.51.100.42",
          "port": 80
        },
        "timing": null
      }
    },
    {
      "type": "requestfinished",
      "request": {
        "type": "request",
        "url": "https://phishing-redirect.example/login",
        "ts": 1714001210500,
        "headers": {
          "user-agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
          "accept": "text/html,application/xhtml+xml"
        },
        "method": "GET",
        "resourceType": "document",
        "redirectChain": ["http://suspicious-login.net/verify"],
        "postData": ""
      },
      "response": {
        "type": "response",
        "url": "https://phishing-redirect.example/login",
        "ts": 1714001210980,
        "status": 200,
        "headers": {
          "content-type": "text/html; charset=utf-8",
          "set-cookie": "session=abc123; Secure; HttpOnly"
        },
        "remoteAddress": {
          "ip": "198.51.100.42",
          "port": 443
        },
        "timing": null
      }
    },
    {
      "type": "requestfailed",
      "request": {
        "type": "request",
        "url": "https://cdn.tracker.example/pixel.js",
        "ts": 1714001211200,
        "headers": {
          "referer": "https://phishing-redirect.example/login"
        },
        "method": "GET",
        "resourceType": "script",
        "redirectChain": [],
        "postData": ""
      },
      "response": null
    }
  ]
}
This endpoint returns HTTP 404 if the scan did not produce a trace file. This occurs when the scan errored before network capture could complete, or when the html array on the scan record does not contain a second entry. Confirm the scan’s status is done and html has at least two entries before calling this endpoint.
The trace is a powerful tool for threat analysis. Use the redirectChain field on each request to map the full chain of redirects from the submitted URL to the final destination. Filter by method = "POST" entries to detect credential harvesting forms or data exfiltration. Cross-reference remoteAddress.ip values against threat intelligence feeds to identify known malicious infrastructure.

Build docs developers (and LLMs) love