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

# Bulk lookup services

> Accepts between 1 and 100 IP addresses, canonicalizes them, deduplicates Query work, and returns one bounded item for every input position in the original order, including duplicates.



## OpenAPI

````yaml https://api.infrawatch.com/openapi.json?contract=d15375c post /search/services/batch
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/services/batch:
    servers:
      - url: https://api.infrawatch.com/api/v1
    post:
      tags:
        - Search
      summary: Bulk lookup services
      description: >-
        Accepts between 1 and 100 IP addresses, canonicalizes them, deduplicates
        Query work, and returns one bounded item for every input position in the
        original order, including duplicates.
      operationId: batchSearchServices
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/search_v1_IPBatchRequest'
        required: true
        x-codegen-request-body-name: ipBatchRequest
      responses:
        '200':
          content:
            application/json:
              example:
                partial: false
                results:
                  - ip_address: 192.0.2.10
                    status: not_found
              schema:
                $ref: '#/components/schemas/search_v1_ServiceBatchResponse'
          description: >-
            Ordered, bounded service results. Per-IP failures return error items
            and partial=true; failure of the entire operation returns 503.
        '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_IPBatchRequest:
      additionalProperties: false
      description: >-
        The complete encoded JSON request body is limited to 32 KiB (32768
        bytes). CIDRs, IPv6 zones, unknown fields, duplicate JSON keys, and null
        values are rejected.
      examples:
        - ip_addresses:
            - 192.0.2.10
            - 2001:db8::10
            - 192.0.2.10
          limit_per_ip: 10
      properties:
        ip_addresses:
          description: >-
            IPs are canonicalized. Response positions preserve this array's
            order and duplicates.
          items:
            $ref: '#/components/schemas/search_v1_IPAddress'
          maxItems: 100
          minItems: 1
          type: array
        limit_per_ip:
          default: 25
          description: Maximum number of results returned for each input position.
          maximum: 25
          minimum: 1
          type: integer
      required:
        - ip_addresses
      type: object
    search_v1_ServiceBatchResponse:
      additionalProperties: false
      allOf:
        - else:
            properties:
              partial:
                const: false
          if:
            properties:
              results:
                contains:
                  properties:
                    status:
                      const: error
                  required:
                    - status
            required:
              - results
          then:
            properties:
              partial:
                const: true
      properties:
        partial:
          description: >-
            True when at least one per-IP result has status=error because
            bucket-local execution failed. Failure before per-IP results can be
            produced is returned as 503 instead.
          type: boolean
        results:
          description: >-
            One item per requested IP in original input order; duplicate inputs
            produce duplicate response positions.
          items:
            $ref: '#/components/schemas/search_v1_ServiceBatchItem'
          maxItems: 100
          minItems: 1
          type: array
      required:
        - results
        - partial
      type: object
    search_v1_IPAddress:
      description: Canonical IPv4 or IPv6 address. CIDRs and IPv6 zones are not accepted.
      format: ip
      maxLength: 64
      type: string
      x-max-bytes: 64
    search_v1_ServiceBatchItem:
      description: >-
        status=ok includes one or more services and no error; status=not_found
        includes neither services nor error; status=error includes a stable
        error and no services.
      discriminator:
        mapping:
          error: '#/components/schemas/BatchErrorItem'
          not_found: '#/components/schemas/BatchNotFoundItem'
          ok: '#/components/schemas/ServiceBatchOKItem'
        propertyName: status
      oneOf:
        - $ref: '#/components/schemas/search_v1_ServiceBatchOKItem'
        - $ref: '#/components/schemas/search_v1_BatchNotFoundItem'
        - $ref: '#/components/schemas/search_v1_BatchErrorItem'
    search_v1_ErrorResponse:
      additionalProperties: false
      properties:
        error:
          $ref: '#/components/schemas/search_v1_ErrorDetail'
      required:
        - error
      type: object
    search_v1_ServiceBatchOKItem:
      additionalProperties: false
      properties:
        ip_address:
          $ref: '#/components/schemas/search_v1_IPAddress'
        results_truncated:
          description: >-
            True when more services matched this IP than the requested
            limit_per_ip.
          type: boolean
        services:
          items:
            $ref: '#/components/schemas/search_v1_ServiceSummary'
          maxItems: 25
          minItems: 1
          type: array
        status:
          enum:
            - ok
          type: string
      required:
        - ip_address
        - status
        - services
        - results_truncated
      type: object
    search_v1_BatchNotFoundItem:
      additionalProperties: false
      properties:
        ip_address:
          $ref: '#/components/schemas/search_v1_IPAddress'
        status:
          enum:
            - not_found
          type: string
      required:
        - ip_address
        - status
      type: object
    search_v1_BatchErrorItem:
      additionalProperties: false
      properties:
        error:
          $ref: '#/components/schemas/search_v1_BatchItemError'
        ip_address:
          $ref: '#/components/schemas/search_v1_IPAddress'
        status:
          enum:
            - error
          type: string
      required:
        - ip_address
        - status
        - error
      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_ServiceSummary:
      additionalProperties: false
      properties:
        banner_preview:
          maxLength: 512
          type: string
        domain:
          maxLength: 253
          minLength: 1
          type: string
        last_scanned_at:
          format: date-time
          type: string
        port:
          maximum: 65535
          minimum: 1
          type: integer
        protocol:
          maxLength: 128
          minLength: 1
          type: string
        status:
          maxLength: 128
          minLength: 1
          type: string
        tags:
          items:
            $ref: '#/components/schemas/search_v1_Tag'
          maxItems: 8
          type: array
        transport:
          maxLength: 128
          minLength: 1
          type: string
      required:
        - port
        - tags
      type: object
    search_v1_BatchItemError:
      additionalProperties: false
      properties:
        code:
          description: Stable per-IP failure category.
          enum:
            - search_bucket_failed
            - search_result_invalid
          type: string
      required:
        - code
      type: object
    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
  responses:
    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

````