> ## Documentation Index
> Fetch the complete documentation index at: https://docs.infrawatch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Measure infrastructure

> Count a search and group matching infrastructure by public fields

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.

<Note>
  Count and aggregate require the `search.aggregate` scope.
</Note>

## Inspect results first

Start with a normal search to confirm the query matches the intended
infrastructure:

```bash theme={null}
curl --get "https://api.infrawatch.com/api/v1/search/hosts" \
  --header "X-API-Key: ${INFRAWATCH_API_KEY}" \
  --data-urlencode "q=services.protocol:ssh" \
  --data "limit=25"
```

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:

```bash theme={null}
curl --get "https://api.infrawatch.com/api/v1/search/hosts/count" \
  --header "X-API-Key: ${INFRAWATCH_API_KEY}" \
  --data-urlencode "q=services.protocol:ssh"
```

## Group the population

This request groups matching hosts by country and observed service port:

```bash theme={null}
curl --request POST \
  --url "https://api.infrawatch.com/api/v1/search/hosts/aggregate" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: ${INFRAWATCH_API_KEY}" \
  --data '{
    "query": "services.protocol:ssh",
    "aggregations": [
      {"field": "country_code", "limit": 10},
      {"field": "services.port", "limit": 10}
    ]
  }'
```

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

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

## Measure a single host

Those same counters answer questions in one clause, without an aggregation at
all. Each summarizes the host's current services:

| Question                                                   | Clause                |
| ---------------------------------------------------------- | --------------------- |
| Is this a multi-tenant front rather than one tenant's box? | `distinct_domains>50` |
| Does one address serve several different web stacks?       | `distinct_servers>3`  |
| How wide is this host's exposure?                          | `service_count>10`    |
| Is the TLS estate unusually varied?                        | `distinct_certs>20`   |

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

<CardGroup cols={2}>
  <Card title="Build a service hunt" icon="https://mintcdn.com/infrawatch/gCEz_Bv1hOrMPG8n/images/products/use-cases.svg?fit=max&auto=format&n=gCEz_Bv1hOrMPG8n&q=85&s=038f2239f51bdde5dd89ff8ef00d88e9" href="/use-cases/hunt-exposed-services" width="32" height="32" data-path="images/products/use-cases.svg">
    Turn a detection hypothesis into a reviewed search before measuring it.
  </Card>

  <Card title="Aggregation contract" icon="https://mintcdn.com/infrawatch/gCEz_Bv1hOrMPG8n/images/products/api.svg?fit=max&auto=format&n=gCEz_Bv1hOrMPG8n&q=85&s=50b239ba7ccf3ebb74f6b239980bc623" href="/api-reference/introduction" width="32" height="32" data-path="images/products/api.svg">
    Browse request limits, bucket schemas, and endpoint responses.
  </Card>
</CardGroup>