---
title: "Aggregate results for a search query within a collection"
method: POST
path: "/v3/collections/{collection_uid}/search/aggregate"
tags: ["Collections"]
---

# Aggregate results for a search query within a collection

`POST /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](https://docs.censys.com/docs/platform-report-builder#/) in the Platform web UI.

## Path parameters

- `collection_uid` string, uuid, required — The UID for the collection. Obtain the collection ID using the [list collections endpoint](https://docs.censys.com/reference/v3-collections-crud-list#/) or via the collection URL when using 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.

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

## Request body

- SearchAggregateInputBody
  - `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 — 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` integer, required — number of buckets to split results into
  - `query` string, required — CenQL query string to search upon

## Response `200`

OK

- ResponseEnvelopeSearchAggregateResponse
  - `result` SearchAggregateResponse
    - `buckets` SearchAggregateResponseBucket[], nullable, required
      - `count` integer, required
      - `key` string, required
    - `is_more_than_total_hits` boolean, required
    - `other_count` integer, required
    - `query_duration_millis` integer, required
    - `total_count` integer, required

## Other responses

- `400` — Bad request
- `401` — Request does not contain a valid Authorization token
- `403` — User does not have permission to access this data
- `404` — No collection found
- `422` — Invalid input
- `500` — Internal server error

---

[API](https://skmtc.net/censys/apis/censys-platform-api.md) · [All operations](https://skmtc.net/censys/apis/censys-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/censys/censys-platform-api/versions/261c916bf05b/schema)