Censys · Schema

SearchAggregateInputBody

SearchAggregateInputBody schema from Censys Platform API

SecurityInternet IntelligenceAttack Surface ManagementThreat HuntingCyber Threat IntelligenceOSINTInternet ScanningCertificatesAsset Discovery

Properties

Name	Type	Description
count_by_level	string	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 aggreg
field	string	field to aggregate by
filter_by_query	boolean	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, aggrega
number_of_buckets	integer	number of buckets to split results into
query	string	CenQL query string to search upon

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/censys/refs/heads/main/json-schema/platform-searchaggregateinputbody-schema.json",
  "title": "SearchAggregateInputBody",
  "description": "SearchAggregateInputBody schema from Censys Platform API",
  "type": "object",
  "properties": {
    "count_by_level": {
      "description": "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.",
      "type": "string"
    },
    "field": {
      "description": "field to aggregate by",
      "examples": [
        "host.services.port"
      ],
      "type": "string"
    },
    "filter_by_query": {
      "default": false,
      "description": "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.",
      "type": "boolean"
    },
    "number_of_buckets": {
      "description": "number of buckets to split results into",
      "examples": [
        "100"
      ],
      "format": "int64",
      "maximum": 2000,
      "minimum": 1,
      "type": "integer"
    },
    "query": {
      "description": "CenQL query string to search upon",
      "examples": [
        "host.services.protocol=SSH"
      ],
      "type": "string"
    }
  },
  "required": [
    "query",
    "field",
    "number_of_buckets"
  ],
  "additionalProperties": false
}