---
title: "Get a list of risk changes for monitored vendors"
method: GET
path: "/risks/vendors/diffs"
tags: ["risks"]
---

# Get a list of risk changes for monitored vendors

`GET /risks/vendors/diffs`

## Request

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

Returns a list of the risks introduced and risks resolved for domains or IPs between two dates across your monitored vendors.

The maximum allowed interval is 30 days.

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

## Query parameters

- `start_date` string, date-time, required
- `end_date` string, date-time
- `page_token` string
- `page_size` integer

## Response `200`

Risks introduced and resolved

- VendorsRisksDiffResponsePayloadBody
  - `next_page_token` string: The token to be used to retrieve the next page of results. Will not be returned if there are no more results.
  - `total_results` integer: The total number of vendors found.
  - `vendors` VendorsRiskDiffs[]: The list of vendors found
    - `id` integer: The id of the vendor. Its possible for a hostname to change which vendor it belongs to for a number of reasons (eg. Company's legal entity changes, improved data quality, etc...). For this reason, do not assume a hostname will always return the same vendor id.
    - `name` string: The name of the vendor
    - `primary_hostname` string: The primary hostname of the vendor
    - `risksIntroduced` RiskDiffGroup[]: The risks introduced between start date and end date grouped by class, including previously provisional risks
      - `groupID` string: The ID of the risk group
      - `highestSeverity` 0 | 1 | 2 | 3 | 4 | 5: The highest severity of the risks in this group
      - `highestSeverityName` 'pass' | 'info' | 'low' | 'medium' | 'high' | 'critical': The highest severity of the risks in this group in human-readable form
      - `name` string: The name of the risk group
      - `risks` RiskDiff[]: The list of risks in this group
        - `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 category of the risk group
        - `description` string: Description or context surrounding the risk
        - `group` string: The ID of the risk class
        - `id` string: The ID of risk
        - `name` string: The name of the risk
        - `remediation` string: Remediation recommendation
        - `riskDetails` string: Detailed 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
        - `scanDiffs` ScanDiff[]: The differences between our automated scans
          - `expected` string: The expected status
          - `hostname` string: The domain name or IP address experiencing the risk diff
          - `property` string: The property checked
          - `scanA` ScanResult
            - `date` string, date-time: The date of the scan (RFC 3339 format)
            - `metaValue` string: Metadata for the result of the check
            - `status` 'PASS' | 'FAIL' | 'UNKNOWN' | 'WAIVED': The check status after the automated scan
          - `scanB` ScanResult
            - `date` string, date-time: The date of the scan (RFC 3339 format)
            - `metaValue` string: Metadata for the result of the check
            - `status` 'PASS' | 'FAIL' | 'UNKNOWN' | 'WAIVED': The check status after the automated scan
        - `severity` 0 | 1 | 2 | 3 | 4 | 5: The severity of the risk
        - `severityName` 'pass' | 'info' | 'low' | 'medium' | 'high' | 'critical': The severity of the risks in human-readable form
        - `vendorDiff` VendorDiff
          - `expected` string: The expected status
          - `metaValueA` string: Metadata for the result of the first check
          - `metaValueB` string: Metadata for the result of the second check
          - `prevProvisionalID` string: Previous provisional ID if the last scan contained it
          - `statusA` string
          - `statusB` string
    - `risksResolved` RiskDiffGroup[]: The risks resolved between start date and end date grouped by class
      - `groupID` string: The ID of the risk group
      - `highestSeverity` 0 | 1 | 2 | 3 | 4 | 5: The highest severity of the risks in this group
      - `highestSeverityName` 'pass' | 'info' | 'low' | 'medium' | 'high' | 'critical': The highest severity of the risks in this group in human-readable form
      - `name` string: The name of the risk group
      - `risks` RiskDiff[]: The list of risks in this group
        - `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 category of the risk group
        - `description` string: Description or context surrounding the risk
        - `group` string: The ID of the risk class
        - `id` string: The ID of risk
        - `name` string: The name of the risk
        - `remediation` string: Remediation recommendation
        - `riskDetails` string: Detailed 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
        - `scanDiffs` ScanDiff[]: The differences between our automated scans
          - `expected` string: The expected status
          - `hostname` string: The domain name or IP address experiencing the risk diff
          - `property` string: The property checked
          - `scanA` ScanResult
            - `date` string, date-time: The date of the scan (RFC 3339 format)
            - `metaValue` string: Metadata for the result of the check
            - `status` 'PASS' | 'FAIL' | 'UNKNOWN' | 'WAIVED': The check status after the automated scan
          - `scanB` ScanResult
            - `date` string, date-time: The date of the scan (RFC 3339 format)
            - `metaValue` string: Metadata for the result of the check
            - `status` 'PASS' | 'FAIL' | 'UNKNOWN' | 'WAIVED': The check status after the automated scan
        - `severity` 0 | 1 | 2 | 3 | 4 | 5: The severity of the risk
        - `severityName` 'pass' | 'info' | 'low' | 'medium' | 'high' | 'critical': The severity of the risks in human-readable form
        - `vendorDiff` VendorDiff
          - `expected` string: The expected status
          - `metaValueA` string: Metadata for the result of the first check
          - `metaValueB` string: Metadata for the result of the second check
          - `prevProvisionalID` string: Previous provisional ID if the last scan contained it
          - `statusA` string
          - `statusB` string

## Other responses

- `403`: Your API key does not have permission to perform this action.
- `404`: The vendor was not found.
- `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)