Skip to main content
Search returns matching evidence. Count and aggregate answer analytical questions about the full matching population and are separate operations so you request the more expensive analysis only when it matters.
Count and aggregate require the search.aggregate scope.

​
Inspect results first

Start with a normal search to confirm the query matches the intended infrastructure:
The search pagination total can be exact or an honest lower bound. Check pagination.total_relation:
  • eq: total is exact.
  • gte: total is a lower bound.

​
Request an exact count

Call count only when the exact total matters:

​
Group the population

This request groups matching hosts by country and observed service port:
Each group identifies:
  • field: the public field that was grouped.
  • count_unit: what each bucket count represents.
  • buckets: typed values and counts.
  • relation: whether counts are exact or lower bounds.
  • has_more: whether more buckets exist.
  • sampled: whether sampling affected the group.
Callers choose reviewed public fields only. Backend aggregation configuration and storage details are not part of the API. The hosts dataset groups by eight fields: services.port, services.protocol, country_code, asn, tags, service_ports, service_protocols, and service_transports.
The host summary counters, such as service_count, distinct_domains, distinct_servers, distinct_certs, and distinct_ja4s, are filters rather than dimensions. Passing one as an aggregation field is rejected with an error rather than silently ignored.

​
Measure a single host

Those same counters answer questions in one clause, without an aggregation at all. Each summarizes the host’s current services:
Host-level counters measure spread across what a host exposes now. The service-level distinct_* fields, reached as services.distinct_banners and similar, measure churn on a single service over time. Reach for the first to find sprawl, and the second to find something that keeps changing.

Build a service hunt

Turn a detection hypothesis into a reviewed search before measuring it.

Aggregation contract

Browse request limits, bucket schemas, and endpoint responses.