Aggregate results for a search query within a collection

post

https://api.platform.censys.io/v3/collections/{collection_uid}/search/aggregate

Aggregate results for a Platform search query that targets a collection's assets. This functionality is equivalent to the Report Builder in the Platform web UI.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

collection_uid

uuid

required

The UID for the collection. Obtain the collection ID using the list collections endpoint or via the collection URL when using the web console.

Body Params

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 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.

field

string

required

field to aggregate by

filter_by_query

boolean

Defaults to false

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_buckets

int64

required

1 to 2000

number of buckets to split results into

query

string

required

CenQL query string to search upon

Query Params

organization_id

uuid

required

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

Headers

X-Organization-ID

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.

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

200OK

400Bad request

401Request does not contain a valid Authorization token

403User does not have permission to access this data

404No collection found

422Invalid input

500Internal server error