Hosts Aggregate API

The Hosts Aggregate API exposes a single endpoint, /api/v2/hosts/aggregate, which allows for generating bucket-based aggregation statistics about a specific data field for Hosts which match a given query using the Censys Search Language.

Details

Description

Aggregates hosts that match the given query string into buckets based on the given field. See help on the Censys Search Language for help on constructing a search query.

Endpoint
GET /api/v2/hosts/aggregate
Path Parameters
(none)
Query Parameters
  • field [required string]
    The field used to aggregated upon and generate buckets for. If the field is a service level field, the aggregation result will be based on services which belong to hosts which match the query, not the hosts themselves.
  • q [optional string]
    Query used to search for Hosts which will be aggregated. Query uses the Censys Search Language.
  • num_buckets [optional int]
    The maximum number of buckets used to generate aggregate results. The final number of buckets may be less than this number. Minimum of 1. If not specified, 50 buckets will be used by defualt.
Example: /api/v2/hosts/aggregate?field=services.port&q=services.service_name%3AHTTP&num_buckets=200
Aggregates Hosts which have an HTTP service by their ports. Bucket results in a maximum of 200 top results.
Body Parameters
(none)
Success Response
200 SUCCESS
The aggregation executed successfully.
Example:
{
  "buckets":[
     {
        "count":23596633,
        "key":"443"
     },
     {
        "count":22655719,
        "key":"80"
     },
     {
        "count":17419067,
        "key":"7547"
     }
  ],
  "query": "services.service_name: HTTP",
  "field": "services.port",
  "total":102305884,
  "total_omitted":200917305
}