---
title: "List risk instances"
method: GET
path: "/v1/supplychains/{supply_chain_id}/risk-instances"
tags: ["Supplier Risk"]
---

# List risk instances

`GET /v1/supplychains/{supply_chain_id}/risk-instances`

## Request

- Base URL: `https://api.platform.censys.io`
- URL: `https://api.platform.censys.io/v1/supplychains/{supply_chain_id}/risk-instances`
- Auth: HTTP bearer

Retrieve individual risk instances (one risk type observed on one asset belonging to one supplier) across your supply chain. By default the entire supply chain is searched. Provide `supplier_ids` to narrow your search.<br><br>For risk-type aggregations, use the [list risks endpoint](https://docs.censys.com/reference/v1-supply-chain-list-risks).

## Path parameters

- `supply_chain_id` string, required: The ID of a Censys supply chain, or the literal 'default' for your organization's primary supply chain. Obtain the supply chain ID using the [list supply chains endpoint](https://docs.censys.com/reference/v1-supply-chain-list-supply-chains#/) or from the Supplier Risk URL in the web console.

## Query parameters

- `organization_id` string, uuid, required: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
- `supplier_ids` string[], nullable: Narrow the search to one or more Censys suppliers in the supply chain. For multiple values, include comma-separated values. When omitted, the entire supply chain is searched.
- `query` string: A CenQL query. When provided, must reference at least one risk field, for example risk.severity. Combined with severity/risk_type/resource_type/rapid_response, if set, using AND.
- `severity` 'UNSPECIFIED' | 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL': Filter to a single risk severity. When omitted, every severity is included.
- `risk_type` 'misconfigs' | 'vulns' | 'exposures' | 'threats': Filter to a single risk category. When omitted, misconfigurations, vulnerabilities, exposures, and threats are all included.
- `resource_type` 'hosts' | 'web': Filter to risks observed on a single asset resource type. When omitted, hosts and web are both included.
- `rapid_response` boolean: When true, filter to risk instances flagged for rapid response. When omitted or false, no filter is applied on this field.
- `order_by` 'last_detected_at_asc' | 'last_detected_at_desc' | 'created_at_asc' | 'created_at_desc': Sort order. When omitted, results are returned in the backend's default order.
- `page_size` integer: Maximum number of risk instances to return per page.
- `page_token` string: Pagination token from a previous response to retrieve the next page of results.

## Headers

- `X-Organization-ID` string, uuid: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.

## Response `200`

Risk instances returned successfully

- ResponseEnvelopeSupplyChainSearchRisksResponse
  - `result` SupplyChainSearchRisksResponse
    - `next_page_token` string: Pagination token for the next page of results, if any.
    - `previous_page_token` string: Pagination token for the previous page of results, if any.
    - `query_duration_millis` integer, required: The amount of time, in milliseconds, the search took to run.
    - `risk_instances` RiskInstance[], nullable, required: Risk instances matching the search.
      - `asset_type` string, required: Which asset type the locus fields describe, e.g. host or web.
      - `confidence` number, double, required: Confidence that this finding is real, from 0 to 1.
      - `created_at` string, date-time: When the instance record was created in Censys.
      - `description` string: Description of this risk.
      - `evidence` string: Evidence supporting the identification of this risk on this asset.
      - `first_detected_at` string, date-time: When this risk instance was first observed.
      - `host` SupplyChainRiskInstanceHost
        - `ip` string, required: IP address of the host this risk was observed on.
      - `id` string, required: Unique identifier of this risk instance.
      - `last_detected_at` string, date-time: Most recent time this risk instance was observed.
      - `platform_url` string, uri: Deep link to the asset this risk was observed on, in the context of this supply chain and supplier, if the asset type is recognized.
      - `rapid_response` boolean, required: Whether this risk type was authored as a rapid response to an emerging threat.
      - `remediations` string[], nullable: Recommended remediation steps for this risk, in the order they should be applied.
      - `resolve_reason` 'finding_removed' | 'service_removed' | 'web_property_removed' | 'asset_removed': Why this risk instance resolved. Present only when status is closed.
      - `resolve_time` string, date-time: When this risk instance resolved. Present only when status is closed; absent while open, and cleared again if the instance later reopens.
      - `risk_category` 'VULNERABILITY' | 'EXPOSURE' | 'MISCONFIGURATION' | 'THREAT', required: Category of this risk.
      - `risk_name` string, required: Human-readable name of this risk, e.g. "Unencrypted HTTP Weak Auth".
      - `risk_type_id` string, required: Risk identifier shared across every instance of this risk, e.g. a CVE ID or a Censys catalog ID.
      - `score` number, double, required: Priority score from 0.0-10.0, derived from asset importance, severity, and exploitability.
      - `service` SupplyChainRiskInstanceService
        - `port` integer, required: Port the service runs on.
        - `protocol` string, required: Application protocol identified on the service, e.g. SSH, HTTP.
        - `transport_protocol` string, required: Transport protocol of the service, e.g. TCP, UDP, ICMP, QUIC.
      - `severity` 'UNSPECIFIED' | 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL', required: Severity of this risk.
      - `status` 'open' | 'closed', required: Status of this risk instance: open or closed.
      - `suppliers` SupplyChainRiskInstanceSupplier[], nullable: Suppliers this risk instance's asset belongs to.
        - `display_name` string: Display name of the supplier.
        - `id` string, uuid, required: Unique ID of the supplier.
      - `supply_chain_id` string, uuid, required: The supply chain this risk instance belongs to.
      - `tags` SearchQueryTagInfo[], nullable: Tags applied to the parent asset as of when this risk was last observed.
        - `display_name` string, required: Name of the tag.
        - `id` string, uuid: ID of the tag.
      - `web` SupplyChainRiskInstanceWeb
        - `hostname` string, required: Hostname of the web property this risk was observed on.
        - `port` integer, required: Port of the web property this risk was observed on.
    - `supply_chain_id` string, uuid, required: The supply chain that was searched, resolved from 'default' if that was given.
    - `total_hits` integer, required: Total number of risk instances matching the search.

## Other responses

- `400`: Invalid arguments
- `401`: Request does not contain a valid Authorization token
- `403`: User does not have permission to access this data
- `404`: Resource not found
- `409`: Conflict
- `422`: Invalid inputs
- `500`: Internal server error

## Changes

- **2026-11-03** `ec1686b0a36a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/censys/apis/censys-platform-api/changes/v1/supplychains/:supply_chain_id/risk-instances/get.md)

---

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