> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.darknetsearch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Read assessment report data

> Pull the structured findings behind a finished assessment report as JSON: list what it holds, read one section by path and fetch an evidence dataset as rows.

Every completed assessment report stores its findings as structured JSON. Three endpoints read that data, so you can load findings into your own tools without parsing the PDF:

* **The index** lists the report's sections and datasets.
* **A section** returns one part of the report, such as the credential exposure module or the security scorecard.
* **A dataset** returns one evidence table as columns and rows, the same table the PDF bundle ships as a CSV file.

They work on any report in `completed` status: automatic or generated, PDF or JSON format. The one exception is the dataset endpoint on a Domain Spoofing Risk Report. See [Pull a dataset](#pull-a-dataset). You need the report's `uid`, which [Generate and download assessment reports](https://wiki.darknetsearch.com/api/guides/attack-surface-reports.md) shows how to find.

### Availability and cost

**Availability:** Attack Surface Reports or Targeted Attack Surface Reports, included in every edition. Either feature opens every endpoint on this page.

**Cost:** no metered allowance. Reading report data uses none of your Attack Surface allowances. With an API key, each call that returns `2xx` counts once toward your monthly API Calls allowance. Any other status is refunded. See [Rate limits](https://wiki.darknetsearch.com/api/guides/rate-limits.md).

Without either feature, every call on this page returns `403` with `{"detail": "This feature is not included in your plan."}`. A lapsed license returns the same message here. These endpoints never return the allowance `429` or a capacity `409`. See [Plans and quotas](https://wiki.darknetsearch.com/api/guides/plans-and-quotas).

### Discover what a report holds

[`GET /api/hackerview/reports/{report_uid}/data/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/GET/api/hackerview/reports/\{report_uid}/data/) returns the report's top-level sections and its datasets.

```bash theme={"dark"}
curl https://client-api.leak.center/api/hackerview/reports/8d1f5c2a-3b7e-4c9d-a1f0-6e2b4c8d9a10/data/ \
  -H "X-API-Key: YOUR_API_KEY"
```

```json theme={"dark"}
{
  "sections": {
    "meta": {"type": "dict", "keys": ["report_uid", "scan_uid", "domain", "original_domain", "scan_domains", "ip", "status", "params", "email_domain_info", "created_at", "completed_at", "elapsed_time_seconds", "generated_at", "language"]},
    "security_scorecard": {"type": "dict", "keys": ["overall_score", "overall_severity", "categories", "top_risky_assets"]},
    "servers": {"type": "list", "count": 42},
    "modules": {"type": "dict", "keys": ["dns_posture", "credential_exposure", "tls_posture", "web_app_security", "vuln_verification"]},
    "exclusions_applied": {"type": "dict", "keys": ["suppressed", "tag_only", "persons", "cves", "findings", "emails", "domains", "social", "urls"]}
  },
  "datasets": ["assets", "credential_exposure", "dns_checks", "tls_posture", "vulnerabilities"]
}
```

The example is shortened. A real full report has more sections and datasets.

* **`sections`** has one entry per top-level key. `type` is `dict` for an object, with its keys in `keys`, or `list` for an array, with its length in `count`. A plain value shows its type, such as `str` or `int`. Keys whose value is `null` are left out.
* **`datasets`** names the evidence tables the report produced. It can include tables that the [dataset endpoint](#pull-a-dataset) does not serve, such as `risky_ports`, `credential_exposure_summary` or the `emails_` tables. Those exist only as CSV files in the ZIP of a PDF-format report.

#### Sections of the full report

The Full Attack Surface Report, and the risk reports built on it, hold these top-level sections:

| Section | What it holds |
| - | - |
| `meta` | The report and assessment: IDs, domains, start options in `params`, timestamps and the report `language` |
| `executive_summary` | The narrative summary as HTML, and the top actions |
| `security_scorecard` | The overall score and severity, the category scores and the riskiest hosts |
| `module_report_states` | Whether IP range discovery, IP range validation and cloud exposure finished, for the chapters that depend on them |
| `servers` | The hosts found: `fqdn`, `ip`, `open_ports`, `software`, `vulns`, `risk_score`, `is_excluded` and more |
| `modules` | One object per module, such as `dns_posture`, `credential_exposure`, `tls_posture`, `web_app_security`, `admin_panels`, `email_enumeration`, `spoofguard`, `code_exposure`, `tg_discord_paste` and `vuln_verification` |
| `analysis` | Analysis across modules, such as `vulnerability_landscape`, `tech_stack`, `hosting_providers`, `sensitive_subdomains` and `attack_paths` |
| `llm_assessments` | The written assessments behind the narrative chapters |
| `summaries` | Counts and summaries: `counts`, `risk_score`, `open_ports`, `vulnerability`, `source`, `source_type` |
| `geo_data`, `ip_ranges`, `network_discoveries` | Where the hosts are and which networks they belong to |
| `brand_related_domains`, `brand_related_rejected_domains` | Other domains that carry your brand, kept or rejected as related |
| `temporal` | Which findings are new or recurring compared with earlier assessments of the domain |
| `top_risky_employees`, `ransomware_cost_estimate`, `ransomware_victim_matches` | The most exposed employees, and the ransomware estimate and matches |
| `comparison` | The comparison with the baseline assessment, when the report has one |
| `available_csv_datasets` | The evidence file names, as listed in `datasets` |
| `exclusions_applied` | What your exclusion rules removed. See [What a report left out](#what-a-report-left-out). |

The Domain Spoofing Risk Report, the three activity reports and the Change Comparison have their own layouts. The Domain Spoofing Risk Report holds sections such as `spoofguard`, `phishing_exposure`, `risk` and `exclusions_applied`. Activity and Change Comparison reports hold sections such as `summary`, `adapters`, `source_coverage` and `exclusions_applied`, with `period` on activity reports and `reference_period`, `current_scan` and `baseline_scan` on comparisons. Read the index of each report to see what it holds.

### Read a section

[`GET /api/hackerview/reports/{report_uid}/data/{section}/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/GET/api/hackerview/reports/\{report_uid}/data/\{section}/) returns one section. Use a dot path to reach a key inside it, such as `modules.credential_exposure` or `analysis.tech_stack`.

```bash theme={"dark"}
curl https://client-api.leak.center/api/hackerview/reports/8d1f5c2a-3b7e-4c9d-a1f0-6e2b4c8d9a10/data/meta.language/ \
  -H "X-API-Key: YOUR_API_KEY"
```

```json theme={"dark"}
{
  "section": "meta.language",
  "data": "de"
}
```

* **`data`** holds the value at that path, in the same shape as in the report JSON.
* **Dot paths step through object keys only.** You can't index into a list, so `servers.0` returns `404`. Read `servers` and pick the item yourself.
* **A section comes back whole.** There is no paging, so a large section such as `servers` arrives in one response.
* **`meta.language`** is the language the report was built in. The Domain Spoofing, activity and comparison reports keep it in `language`.

### Pull a dataset

[`GET /api/hackerview/reports/{report_uid}/data/datasets/{name}/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/GET/api/hackerview/reports/\{report_uid}/data/datasets/\{name}/) returns one evidence table as JSON.

```bash theme={"dark"}
curl https://client-api.leak.center/api/hackerview/reports/8d1f5c2a-3b7e-4c9d-a1f0-6e2b4c8d9a10/data/datasets/web_app_security/ \
  -H "X-API-Key: YOUR_API_KEY"
```

```json theme={"dark"}
{
  "dataset": "web_app_security",
  "columns": ["FQDN", "URL", "Check", "Severity", "Confidence", "Base Penalty", "Weighted Penalty", "Path Multiplier", "Short Evidence", "Aliases"],
  "count": 1,
  "rows": [
    {
      "FQDN": "portal.acme.com",
      "URL": "https://portal.acme.com/",
      "Check": "HSTS_MISSING",
      "Severity": "low",
      "Confidence": "1.0",
      "Base Penalty": "0.5",
      "Weighted Penalty": "0.5",
      "Path Multiplier": "1.0",
      "Short Evidence": "HSTS header missing",
      "Aliases": ""
    }
  ]
}
```

* **`columns`** lists the column names in order. Each row is an object keyed by those names.
* **`count`** is the number of rows. All rows come back in one response.
* **Values in the full report and the risk reports are strings**, exactly as in the CSV file, numbers included. Activity and comparison reports return their values with their JSON types.

The endpoint serves these names and no others:

| Area | Datasets |
| - | - |
| Hosts and vulnerabilities | `assets`, `vulnerabilities`, `host_vulnerabilities`, `nuclei_findings`, `ip_ranges`, `network_neighbours`, `ssl_cert_domains` |
| DNS, email and TLS | `dns_checks`, `email_auth_checks`, `tls_posture` |
| Web applications | `web_app_security`, `admin_panels` |
| Leaks and exposure | `credential_exposure`, `cloud_exposure`, `domain_exposure`, `shortener_exposure`, `code_exposure`, `tg_discord_paste` |
| Brand and people | `typosquatting`, `brand_related_domains`, `phishing_unattributed_audit`, `social_media`, `email_enumeration`, `vip_intelligence` |
| Assessment status | `module_status` |
| Activity and comparison reports | `activity_findings`, `delta_findings`, `source_coverage`, `module_comparability`, `undated_observations`, `ambiguous_identity_suppressions` |

A report holds only the datasets its modules produced. Check `datasets` in the index first. A name outside the list returns `400`. A name on the list that this report does not hold returns `404`.

> [!NOTE]
>
> On a Domain Spoofing Risk Report, the dataset endpoint does not serve the tables its index lists: `typosquatting` and `phishing_unattributed_audit` return `404`, and `phishing_exposure` returns `400`. Read the same data with the [section endpoint](#read-a-section): `spoofguard` for the look-alike domains, `phishing_listings` and `phishing_exposure` for the phishing listings. A PDF-format report also ships them as CSV files in its ZIP.

### What a report left out

`exclusions_applied` counts what your [exclusion rules](https://wiki.darknetsearch.com/api/guides/attack-surface-exclusions.md) removed when the report was built. Read it with the section endpoint:

```bash theme={"dark"}
curl https://client-api.leak.center/api/hackerview/reports/8d1f5c2a-3b7e-4c9d-a1f0-6e2b4c8d9a10/data/exclusions_applied/ \
  -H "X-API-Key: YOUR_API_KEY"
```

In the full report and the snapshot risk reports, it has nine counters. Each is `0` when nothing was removed:

| Counter | Counts |
| - | - |
| `suppressed` | Hosts removed from the report and the scores |
| `tag_only` | Hosts kept but marked as excluded, with scores unchanged |
| `persons` | People removed from the executive and high-value-target lists |
| `emails` | Email addresses removed |
| `cves` | CVEs removed from the vulnerability findings |
| `findings` | Single findings removed |
| `domains` | Domains removed from breach results, or accepted as legitimate in the Domain Spoofing report |
| `social` | Social media accounts removed |
| `urls` | Exposed URLs removed |

Activity and Change Comparison reports use another shape: `total` removed, `by_rule` and `by_adapter` breakdowns, `rules_loaded`, and `rules_hash`, a fingerprint of the rules that applied. Two reports with the same `rules_hash` were built with the same rules.

The counters give totals per kind of rule, not per rule. Rules apply when a report is built, so after you change them, [generate the report again](https://wiki.darknetsearch.com/api/guides/attack-surface-reports.md#regenerate-a-report) and read the new report.

### Errors

| Status | When | Body |
| - | - | - |
| `400` | The report is not `completed` yet, or it failed | `{"error": "Report not ready."}` |
| `400` | The dataset name is not on the list | `{"error": "Unknown dataset \"x\". Valid: [...]"}` |
| `403` | Your plan has neither Attack Surface feature, or your license is not active | See [Availability and cost](#availability-and-cost) |
| `404` | No report with that `uid` in your organization | `{"error": "Report not found."}` |
| `404` | The path does not exist in the report | `{"error": "Section \"x\" not found. Available top-level keys: [...]"}` |
| `404` | The report does not hold that dataset | `{"error": "No data available for dataset \"x\" in this report."}` |
| `404` | The report's stored data is missing | `{"code": "report_data_missing", "error": "..."}`. [Generate the report again](https://wiki.darknetsearch.com/api/guides/attack-surface-reports.md#regenerate-a-report). |
| `404` | `report_uid` is not a UUID | An HTML page |
| `409` | The report must be regenerated before it can be read | `{"code": "report_regeneration_required", "error": "...", "regeneration_required": true}`. Generate it again. |
| `429` | The per-second rate limit or the API Calls allowance | See [Rate limits](https://wiki.darknetsearch.com/api/guides/rate-limits.md) |
| `502` | The stored data is damaged, or the assessment service failed | `{"detail": "The requested service is temporarily unavailable."}`. If it repeats for one report, generate it again. |
| `504` | The assessment service timed out | `{"detail": "The requested service timed out."}` |

### Endpoints

| Action | Endpoint |
| - | - |
| List a report's sections and datasets | [`GET /api/hackerview/reports/{report_uid}/data/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/GET/api/hackerview/reports/\{report_uid}/data/) |
| Read one section | [`GET /api/hackerview/reports/{report_uid}/data/{section}/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/GET/api/hackerview/reports/\{report_uid}/data/\{section}/) |
| Read one dataset | [`GET /api/hackerview/reports/{report_uid}/data/datasets/{name}/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/GET/api/hackerview/reports/\{report_uid}/data/datasets/\{name}/) |
| List reports, to find `report_uid` | [`GET /api/hackerview/reports/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/GET/api/hackerview/reports/) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.