---
title: "List hostnames and their risks"
method: GET
path: "/bulk/hostnames"
tags: ["bulk"]
---

# List hostnames and their risks

`GET /bulk/hostnames`

## Request

- Base URL: `https://cyber-risk.upguard.com/api/public`
- URL: `https://cyber-risk.upguard.com/api/public/bulk/hostnames`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/upguard/apis/upguard-cyberrisk-api/docs/bulk/hostnames/get.ts> (a function with typed inputs; its response is checked against the schema)

Get the list of registered hostnames and their risks. You can use the omit_risks,
omit_vendor, omit_score and omit_labels query parameter to turn off these information
from the response and quickly get a list of registered hostnames.

This is an add-on endpoint not available to all accounts. Please contact support for information about bulk endpoints and how to upgrade your account.

Required API key permissions: `Admin` (select when creating API key in Account Settings)

## Query parameters

- `page_token` string
- `page_size` integer
- `sort_desc` boolean
- `omit_scan_info` boolean
- `omit_vendor` boolean
- `omit_labels` boolean
- `exclude_active` boolean
- `exclude_inactive` boolean
- `labels` string[]

## Response `200`

Returns the list of hostnames and their risks.

- BulkListHostnamesV1ResponseBody
  - `hostnames` BulkHostname[]: The list of hostnames.
    - `active` boolean: The active state of the hostname. These will be omitted if the omit_scan_info query parameter is true.
    - `automated_score` integer: The automated score of the hostname. This will be omitted if the omit_scan_info query parameter is true.
    - `hostname` string, hostname: The name of the hostname.
    - `labels` string[]: The list of labels associated with the hostname. This will be omitted if the omit_labels query parameter is true.
    - `last_scanned_at` string, date-time: The timestamp this hostname was last scanned at.
    - `risks` BulkRisk[]: The list of risks associated with the hostname. These will be omitted if the omit_scan_info query parameter is true.
      - `category` 'website_sec' | 'email_sec' | 'network_sec' | 'ip_domain_reputation' | 'brand_protect' | 'attack_surface' | 'dns' | 'vulnerability_management' | 'data_leakage' | 'encryption' | 'questionnaire_risks' | 'vulns' | 'typosquatting' | 'emailexposures' | 'dataleaks' | 'additional_evidence': The risk category identifier
      - `description` string: A long description of the risk
      - `finding` string: A short description of the finding
      - `id` string: The risk identifier
      - `risk` string: A short description of the risk
      - `riskSubtype` string: The subtype of the risk, e.g. the subtype of the verified_vuln:CVE-2021-34473 is CVE-2021-34473. This field will be empty if the risk has no subtype, e.g. for wp_version_exposed, or for generic risks like verified_vuln:* where the subtype is only determined when the full risk is specified.
      - `riskType` string: The type of the risk, e.g. the type of the verified_vuln:CVE-2021-34473 is verified_vuln
      - `severity` 'pass' | 'info' | 'low' | 'medium' | 'high' | 'critical': The risk severity
    - `vendor` BulkVendor
      - `id` integer: The ID of the vendor.
      - `name` string: The name of the vendor.
      - `primary_hostname` string, hostname: The primary hostname of the vendor.
  - `next_page_token` string: The token to be used to retrieve the next page of results. It will not be returned if there are no more results.
  - `total_results` integer: The total number of hostnames found.

## Other responses

- `403`: Your API key does not have permission to perform this action.
- `422`: An invalid parameter was supplied or a mandatory parameter was missing
- `429`: Too many requests have been made to this endpoint.
- `500`: An internal system error occurred

---

[API](https://skmtc.dev/upguard/apis/upguard-cyberrisk-api.md) - [All operations](https://skmtc.dev/upguard/apis/upguard-cyberrisk-api/llms.txt) - [OpenAPI document](https://skmtc.dev/upguard/apis/upguard-cyberrisk-api/revisions/d044bf6dc61e?raw)