> ## 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. # Aggregate matching WHOIS domain records ## OpenAPI ````yaml https://api.infrawatch.com/openapi.json?contract=d15375c post /search/whois/aggregate openapi: 3.1.0 info: description: >- Customer-facing Infrawatch APIs. Authenticate with an API key unless an operation documents another supported credential. ### Infrawatch Public API Public API authenticated exclusively with Infrawatch API keys. ### Infrawatch Customer Alerting API Project alert rules, destinations, silences, inbox state, and delivery history. ### Infrawatch Remote Browser API Project-scoped interactive browser sessions owned by Platform Core. Session admission, lifecycle, RBAC, audit, usage, screenshot history, and stream tickets are Platform Core resources. The browser master is private infrastructure and its identifiers, proxy routes, process options, and credentials are never exposed by this API. A session and all of its evidence are private to the credential that created it. Project managers may list project session metadata, inspect one session's metadata, and terminate it, but cannot access its live stream, screenshots, or network events. Terminal session metadata and screenshots are retained indefinitely. A creator can replay a terminal session as a new queued resource while preserving a durable link to the source session. ### Infrawatch ESI API Customer-facing External Surface Intelligence API for project-scoped product data authenticated by an Infrawatch API key. API keys are constrained to their immutable owner's project ceiling and assigned ESI scopes; human project-manager fallback never expands an API key. Authorised API-key requests are rate-limited and consume monthly quota. ### Infrawatch Reports API Threat report discovery API authenticated by an Infrawatch API key. ### Infrawatch Public Rules API Account-aware rule authoring, taxonomy, catalogue, and runtime observations for API clients. ### Infrawatch Search API Search hosts, services, DNS records, and certificates. Complete percent-encoded query strings are limited to 65536 bytes. title: Infrawatch Customer API version: 1.0.0 servers: - description: Infrawatch customer API url: https://api.infrawatch.com/api/v1 security: [] tags: - name: API Usage - name: Projects - name: Alert destinations - name: Alert rules - name: Alert silences - name: Alerts - name: Browser sessions - name: Browser evidence - name: Browser streaming - name: Access - name: Inventory - name: Dangling DNS - name: Findings - name: Secrets - name: Typosquatting - name: Services - name: AI Surface - description: Search hosts, services, DNS records, certificates, and open directories. name: Search - name: Dashboard - name: Reports - name: Rules - name: Rule tags - name: Rule observations paths: /search/whois/aggregate: servers: - url: https://api.infrawatch.com/api/v1 post: tags: - Search summary: Aggregate matching WHOIS domain records operationId: aggregateWhois requestBody: content: application/json: schema: $ref: '#/components/schemas/search_v1_AggregateRequest' required: true responses: '200': $ref: '#/components/responses/search_v1_AggregateResponse' '400': $ref: '#/components/responses/search_v1_BadRequest' '401': $ref: '#/components/responses/search_v1_Unauthorized' '403': $ref: '#/components/responses/search_v1_Forbidden' '404': $ref: '#/components/responses/search_v1_NotFound' '413': $ref: '#/components/responses/search_v1_RequestTooLarge' '415': $ref: '#/components/responses/search_v1_UnsupportedMediaType' '429': $ref: '#/components/responses/search_v1_RateLimited' '502': $ref: '#/components/responses/search_v1_UpstreamFailed' '503': $ref: '#/components/responses/search_v1_SearchUnavailable' security: - apiKeyAuth: [] components: schemas: search_v1_AggregateRequest: additionalProperties: false description: >- The complete encoded JSON request body is limited to 32 KiB (32768 bytes). Unknown fields, duplicate JSON keys, and null values are rejected. examples: - aggregations: - field: services.port limit: 25 - field: country_code limit: 25 query: services.protocol:ssh properties: aggregations: description: >- Aggregate fields must be unique after case and whitespace normalization. items: $ref: '#/components/schemas/search_v1_AggregationSpec' maxItems: 8 minItems: 1 type: array query: maxLength: 8192 type: string x-max-bytes: 8192 required: - aggregations type: object search_v1_AggregationSpec: additionalProperties: false properties: field: description: >- Public aggregate field from this dataset's schema. Leading/trailing whitespace is removed and the name is normalized to lowercase. maxLength: 128 minLength: 1 type: string x-max-bytes: 128 limit: default: 25 maximum: 100 minimum: 1 type: integer required: - field type: object search_v1_AggregateResponse: additionalProperties: false properties: groups: items: $ref: '#/components/schemas/search_v1_AggregateGroup' maxItems: 8 minItems: 1 type: array query: maxLength: 8192 type: string x-max-bytes: 8192 required: - query - groups type: object search_v1_ErrorResponse: additionalProperties: false properties: error: $ref: '#/components/schemas/search_v1_ErrorDetail' required: - error type: object search_v1_AggregateGroup: additionalProperties: false allOf: - else: properties: relation: enum: - eq - gte if: properties: sampled: const: true required: - sampled then: properties: relation: const: unknown - else: properties: buckets: items: not: required: - tag if: properties: field: enum: - tags - services.tags required: - field then: properties: value_type: const: string - if: properties: value_type: const: string required: - value_type then: properties: buckets: items: properties: value: type: string - if: properties: value_type: const: integer required: - value_type then: properties: buckets: items: properties: value: type: integer - if: properties: value_type: const: number required: - value_type then: properties: buckets: items: properties: value: type: number - if: properties: value_type: const: boolean required: - value_type then: properties: buckets: items: properties: value: type: boolean properties: buckets: items: $ref: '#/components/schemas/search_v1_AggregateBucket' maxItems: 100 type: array count_unit: enum: - host - service - dns_record - whois_domain - certificate - report type: string field: maxLength: 128 minLength: 1 type: string has_more: type: boolean relation: description: >- eq is exact, gte is a known lower bound, and unknown is a sampled estimate that may be above or below the exact value. enum: - eq - gte - unknown type: string sampled: description: >- True when counts are probabilistic estimates that may be above or below the exact value; sampled groups therefore use relation=unknown. type: boolean value_type: $ref: '#/components/schemas/search_v1_AggregateValueType' required: - field - count_unit - value_type - buckets - relation - has_more - sampled type: object search_v1_ErrorDetail: additionalProperties: false properties: code: description: >- Stable machine-readable category; clients should branch on HTTP status and this value, never on message text. maxLength: 128 minLength: 1 pattern: ^[a-z][a-z0-9_]*$ type: string message: maxLength: 512 minLength: 1 type: string request_id: maxLength: 128 minLength: 1 pattern: ^[A-Za-z0-9_.:-]+$ type: string required: - code - message type: object search_v1_AggregateBucket: additionalProperties: false properties: count: format: int64 maximum: 9007199254740991 minimum: 1 type: integer label: description: >- Optional human-readable display label for a stable bucket identity, such as the ISP name for an ASN value. maxLength: 256 minLength: 1 type: string tag: allOf: - $ref: '#/components/schemas/search_v1_Tag' description: >- Optional closed taxonomy metadata for a tag slug. It is accepted only in tags and services.tags groups, and tag.slug is exactly equal to value. Old Query deployments may omit it. value: $ref: '#/components/schemas/search_v1_AggregateBucketValue' required: - value - count type: object search_v1_AggregateValueType: description: Scalar JSON type used by every bucket value in an aggregate group. enum: - string - integer - number - boolean type: string search_v1_Tag: additionalProperties: false properties: categories: items: description: >- Canonical slash-delimited category path, including its parent paths. maxLength: 128 minLength: 1 pattern: ^[a-z0-9][a-z0-9-]{0,127}(/[a-z0-9][a-z0-9-]{0,127})*$ type: string maxItems: 4 type: array classification: enum: - informational - benign - suspicious - malicious type: string name: maxLength: 256 type: string slug: maxLength: 128 minLength: 1 type: string required: - slug - name - categories - classification type: object search_v1_AggregateBucketValue: description: >- Exact non-null typed scalar bucket identity; objects and arrays are never exposed. oneOf: - maxLength: 4096 minLength: 1 type: string - type: number - type: boolean responses: search_v1_AggregateResponse: content: application/json: examples: dns: summary: DNS record aggregation value: groups: - buckets: - count: 28110532 value: A count_unit: dns_record field: record_type has_more: false relation: eq sampled: false value_type: string - buckets: - count: 816400 value: www.example.com count_unit: dns_record field: host has_more: true relation: gte sampled: false value_type: string - buckets: - count: 1221800 value: example.com count_unit: dns_record field: apex_domain has_more: true relation: gte sampled: false value_type: string - buckets: - count: 27402000 value: NOERROR count_unit: dns_record field: rcode has_more: false relation: gte sampled: false value_type: string - buckets: - count: 284100 value: 192.0.2.10 count_unit: dns_record field: answer has_more: true relation: gte sampled: false value_type: string query: dns.type:A hosts: summary: Host and service aggregation value: groups: - buckets: - count: 5100200 value: 22 count_unit: service field: services.port has_more: true relation: gte sampled: false value_type: integer - buckets: - count: 382100 value: GB count_unit: host field: country_code has_more: true relation: unknown sampled: true value_type: string - buckets: - count: 294100 label: Internet Facing tag: categories: - exposure classification: informational name: Internet Facing slug: internet-facing value: internet-facing count_unit: host field: tags has_more: true relation: gte sampled: false value_type: string - buckets: - count: 182200 label: Remote Access tag: categories: - software/rmm classification: suspicious name: Remote Access slug: remote-access value: remote-access count_unit: service field: services.tags has_more: true relation: gte sampled: false value_type: string - buckets: - count: 128400 label: Remote Monitoring and Management value: software/rmm count_unit: host field: services.tags.category has_more: true relation: unknown sampled: true value_type: string - buckets: - count: 211336 label: MCP value: mcp count_unit: service field: services.http.capabilities has_more: false relation: gte sampled: false value_type: string query: services.protocol:ssh services: summary: Service aggregation value: groups: - buckets: - count: 5100200 value: 22 count_unit: service field: port has_more: true relation: gte sampled: false value_type: integer - buckets: - count: 182200 label: Remote Access tag: categories: - software/rmm classification: suspicious name: Remote Access slug: remote-access value: remote-access count_unit: service field: tags has_more: true relation: gte sampled: false value_type: string - buckets: - count: 128400 label: Remote Monitoring and Management value: software/rmm count_unit: host field: tags.category has_more: true relation: unknown sampled: true value_type: string - buckets: - count: 211336 label: MCP value: mcp count_unit: service field: http.capabilities has_more: false relation: gte sampled: false value_type: string query: protocol:ssh whois: summary: WHOIS domain aggregation value: groups: - buckets: - count: 1840223 value: MarkMonitor Inc. count_unit: whois_domain field: whois.registrar has_more: true relation: gte sampled: false value_type: string - buckets: - count: 1512900 value: clientTransferProhibited count_unit: whois_domain field: whois.status has_more: true relation: gte sampled: false value_type: string - buckets: - count: 402118 value: 'true' count_unit: whois_domain field: whois.dnssec has_more: false relation: eq sampled: false value_type: string query: whois.registrar:"MarkMonitor" schema: $ref: '#/components/schemas/search_v1_AggregateResponse' description: Aggregate groups for the requested fields. search_v1_BadRequest: content: application/json: examples: apiKeyAccountOverride: value: error: code: api_key_account_override message: API keys use their owning account. request_id: req_01JSEARCH countTooExpensive: value: error: code: search_count_too_expensive message: Exact count exceeds the bounded work limit. request_id: req_01JSEARCH invalidAggregation: value: error: code: invalid_aggregation message: Invalid search aggregation. request_id: req_01JSEARCH invalidCursor: value: error: code: invalid_search_cursor message: Search cursor is invalid or expired. request_id: req_01JSEARCH invalidIPBatch: value: error: code: invalid_ip_batch message: Choose between 1 and 100 IP addresses. request_id: req_01JSEARCH invalidJSON: value: error: code: invalid_json message: Invalid JSON request body. request_id: req_01JSEARCH invalidLimitPerIP: value: error: code: invalid_limit_per_ip message: limit_per_ip must be between 1 and 25. request_id: req_01JSEARCH invalidOrganisation: value: error: code: invalid_org_uuid message: Invalid organisation UUID. request_id: req_01JSEARCH invalidPagination: value: error: code: invalid_pagination message: Invalid search pagination. request_id: req_01JSEARCH invalidParameter: value: error: code: invalid_search_parameter message: Unsupported search parameter. request_id: req_01JSEARCH invalidQuery: value: error: code: invalid_search_query message: Invalid search query. request_id: req_01JSEARCH invalidRequest: value: error: code: invalid_request message: >- Dashboard counts do not accept query parameters or a request body. request_id: req_01JSEARCH organisationRequired: value: error: code: organisation_required message: Organisation UUID is required. request_id: req_01JSEARCH schema: $ref: '#/components/schemas/search_v1_ErrorResponse' description: >- Invalid organisation selection, query parameters, pagination, aggregation, JSON body, or IP batch; or an exact count that exceeds its bounded work limit. search_v1_Unauthorized: content: application/json: examples: authentication: value: error: code: unauthorized message: Authentication required. request_id: req_01JSEARCH reauthentication: value: error: code: reauthentication_required message: Reauthentication required. request_id: req_01JSEARCH sessionExpired: value: error: code: session_expired message: Session expired. request_id: req_01JSEARCH schema: $ref: '#/components/schemas/search_v1_ErrorResponse' description: Authentication is missing, invalid, expired, or requires a fresh login. search_v1_Forbidden: content: application/json: examples: csrf: value: error: code: csrf_required message: CSRF token required. request_id: req_01JSEARCH permission: value: error: code: permission_denied message: Permission denied. request_id: req_01JSEARCH schema: $ref: '#/components/schemas/search_v1_ErrorResponse' description: >- The required search scope, active account state, or browser-session CSRF proof is missing. search_v1_NotFound: content: application/json: example: error: code: organisation_not_found message: Organisation not found. request_id: req_01JSEARCH schema: $ref: '#/components/schemas/search_v1_ErrorResponse' description: Selected organisation not found or not visible to the caller. search_v1_RequestTooLarge: content: application/json: example: error: code: request_too_large message: Request body is too large. request_id: req_01JSEARCH schema: $ref: '#/components/schemas/search_v1_ErrorResponse' description: Encoded HTTP request body exceeds 32 KiB (32768 bytes). search_v1_UnsupportedMediaType: content: application/json: example: error: code: unsupported_media_type message: Content-Type must be application/json. request_id: req_01JSEARCH schema: $ref: '#/components/schemas/search_v1_ErrorResponse' description: >- Request body must use unencoded application/json with no charset other than UTF-8. search_v1_RateLimited: content: application/json: examples: account: value: error: code: account_rate_limit_exceeded message: Account rate limit exceeded. request_id: req_01JSEARCH accountQuota: value: error: code: account_api_quota_exceeded message: Monthly API request quota exceeded. request_id: req_01JSEARCH apiKey: value: error: code: api_key_rate_limit_exceeded message: API key rate limit exceeded. request_id: req_01JSEARCH groupQuota: value: error: code: group_api_quota_exceeded message: Monthly group API request quota exceeded. request_id: req_01JSEARCH schema: $ref: '#/components/schemas/search_v1_ErrorResponse' description: >- API-key operational rate limit, human account search rate limit, or API-key monthly account/group quota exceeded. headers: Retry-After: description: Minimum delay in seconds before the active rate-limit window resets. schema: pattern: ^[1-9][0-9]*$ type: string search_v1_UpstreamFailed: content: application/json: example: error: code: search_upstream_failed message: Search service returned an invalid response. request_id: req_01JSEARCH schema: $ref: '#/components/schemas/search_v1_ErrorResponse' description: >- Search service communication failed or returned a malformed, oversized, unexpected, or otherwise invalid response. search_v1_SearchUnavailable: content: application/json: examples: authentication: value: error: code: authentication_unavailable message: Authentication unavailable. request_id: req_01JSEARCH busy: value: error: code: search_busy message: Search is temporarily busy. request_id: req_01JSEARCH configuration: value: error: code: search_service_misconfigured message: Search service is not configured. request_id: req_01JSEARCH entitlement: value: error: code: entitlement_required message: Product unavailable. request_id: req_01JSEARCH metering: value: error: code: api_metering_unavailable message: API metering is temporarily unavailable. request_id: req_01JSEARCH timeout: value: error: code: search_timeout message: Search timed out. request_id: req_01JSEARCH upstreamUnavailable: value: error: code: search_upstream_failed message: Search service is temporarily unavailable. request_id: req_01JSEARCH schema: $ref: '#/components/schemas/search_v1_ErrorResponse' description: >- Search is busy, timed out, unavailable, misconfigured, not enabled for the organisation, or blocked by an unavailable authentication/metering dependency. headers: Retry-After: description: >- Conservative delay in seconds before retrying when the error code is search_busy. schema: pattern: ^[1-9][0-9]*$ type: string securitySchemes: apiKeyAuth: description: >- Infrawatch API key. Supply the complete key directly as the header value. in: header name: X-API-Key type: apiKey ````