CEcensys
Supplier Risk

Aggregate supply chain assets

Changed on

Aggregate assets across your supply chain by a given field. By default, the aggregation covers every supplier in your supply chain. Provide supplier_ids to narrow it to specific suppliers. Use default as the supply chain ID to target your organization's primary supply chain.<br><br>This functionality is equivalent to the Report Builder in the Platform UI.

post/v1/supplychains/{supply_chain_id}/assets/aggregate

Request

Path parameters

supply_chain_idstring 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 or from the Supplier Risk URL in the web console.

Example:11111111-2222-3333-4444-555555555555

Query parameters

organization_idstring uuid required

The ID of a Censys organization to associate the request with. See the Getting Started docs for more information.

Example:11111111-2222-3333-4444-555555555555

Headers

X-Organization-IDstring uuid

The ID of a Censys organization to associate the request with. See the Getting Started docs for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.

Example:11111111-2222-3333-4444-555555555555

Request body

count_by_levelstring

Specifies which document level's count is returned per term bucket, primarily for nested fields. This is the same functionality available in the Count By dropdown in the Report Builder UI. When aggregating on nested fields like 'host.services.port': empty string (default) counts documents at the deepest level containing the field; '.' counts root documents (e.g. counts matching 'host'); 'host.services' counts documents at the specified nested level.

fieldstring required

field to aggregate by

filter_by_queryboolean

Controls whether aggregation results are limited to values that match the query. When true, only field values that satisfy the query constraints are included in aggregation counts. When false, aggregation includes all field values from records that match the query, even if those specific field values don't match the query constraints. For example, if the query is 'host.services.protocol=SSH' and you are aggregating by 'host.services.port' - when true, only shows SSH ports; when false, shows all ports on hosts that have SSH services.

number_of_bucketsinteger required

number of buckets to split results into

querystring required

CenQL query string to search upon

supplier_idsstring[] nullable

The IDs of Censys suppliers in the supply chain to narrow the aggregation to, each as a unique UUID string. When omitted, the entire supply chain is aggregated.

Example request

{
  "field": "host.services.port",
  "query": "host.services.protocol=SSH",
  "supplier_ids": [
    "11111111-2222-3333-4444-555555555555"
  ]
}

Response

Assets aggregated successfully

Changes

  • ec1686b0a36aRevision changes
    • info

      api tag Supplier Risk added

    • info

      api tag Supply Chain Intelligence removed

    • info

      for the path request parameter supply_chain_id, the format was generalized from uuid to no format

    • info

      added the non-success response with the status