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

# Check enrichment status

> Poll a batch while it runs. Free — polling never costs credits.

Prefer the webhook: it tells you the moment the batch lands. Polling is the fallback when you cannot receive one.



## OpenAPI

````yaml /openapi.json get /enrichment/{batch_id}/status
openapi: 3.1.0
info:
  title: BounceWatch API
  version: 1.0.0
  description: >-
    Company enrichment and buying-signal data.


    Every endpoint below is live — put your API key in the panel above and press
    **Send**.


    Account endpoints are free. Enrichment spends credits, and a domain enriched
    within the last 24 hours comes back instantly at no cost.
  contact:
    name: BounceWatch Support
    email: sedat@bouncewatch.com
    url: https://docs.bouncewatch.com
servers:
  - url: https://api.bouncewatch.com/api/v1
    description: Production
security:
  - apiKey: []
tags:
  - name: Company
    description: Enrich a company by domain.
  - name: Enrichment
    description: Track an enrichment batch while it runs, and collect the results.
  - name: Account
    description: >-
      Plan, credits, usage and webhook configuration. None of these consume
      credits.
  - name: Status
    description: Liveness. No key, no credits — point your uptime monitor here.
paths:
  /enrichment/{batch_id}/status:
    get:
      tags:
        - Enrichment
      summary: Check enrichment status
      description: >-
        Poll a batch while it runs. Free — polling never costs credits.


        Prefer the webhook: it tells you the moment the batch lands. Polling is
        the fallback when you cannot receive one.
      operationId: getEnrichmentStatus
      parameters:
        - name: batch_id
          in: path
          required: true
          description: The `batch_id` returned by the 202.
          schema:
            type: string
            examples:
              - batch_1gVwXby8PsYHoMQR
      responses:
        '200':
          description: Current state of the batch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichmentStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: '`batch_forbidden` — that batch belongs to another account.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: '`batch_not_found` — no batch with that id.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    EnrichmentStatus:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - true
        batch_id:
          type: string
          examples:
            - batch_1gVwXby8PsYHoMQR
        domain:
          type: string
          examples:
            - stripe.com
        status:
          type: string
          enum:
            - queued
            - processing
            - completed
            - failed
            - no_data_found
          examples:
            - processing
        requested_modules:
          type: array
          items:
            type: string
          examples:
            - - business
              - technology
        message:
          type:
            - string
            - 'null'
        credits:
          type: object
          properties:
            reserved:
              type: integer
              examples:
                - 20
            used:
              type: integer
              examples:
                - 0
            refunded:
              type: integer
              examples:
                - 0
        timing:
          type: object
          properties:
            requested_at:
              type: string
              format: date-time
            started_at:
              type:
                - string
                - 'null'
              format: date-time
            completed_at:
              type:
                - string
                - 'null'
              format: date-time
            duration_seconds:
              type:
                - number
                - 'null'
        webhook:
          type: object
          properties:
            url:
              type:
                - string
                - 'null'
            sent_at:
              type:
                - string
                - 'null'
              format: date-time
            status:
              type:
                - string
                - 'null'
            retries:
              type: integer
              examples:
                - 0
        results_endpoint:
          type:
            - string
            - 'null'
          description: '`null` until the batch completes.'
    Error:
      type: object
      description: >-
        Every failure carries a machine-readable `error` code. Branch on that,
        never on `message` — the wording changes, the code does not.
      properties:
        success:
          type: boolean
          examples:
            - false
        error:
          type: string
          description: Stable machine-readable code.
          examples:
            - webhook_required
        message:
          type: string
          description: Human-readable explanation. Not stable — do not parse it.
          examples:
            - Webhook URL is required for enrichment requests
        hint:
          type: string
        documentation:
          type: string
      required:
        - success
        - error
  responses:
    Unauthorized:
      description: >-
        `missing_api_key` — no key was sent. `invalid_api_key` — the key is not
        valid. `api_key_disabled`, `ip_not_allowed` and `subscription_required`
        also land here.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing_api_key:
              value:
                success: false
                error: missing_api_key
                message: >-
                  Please provide your API key in X-API-Key header or api_key
                  parameter
    RateLimited:
      description: >-
        `rate_limit_exceeded` — too many requests. `concurrent_limit_reached` —
        too many enrichments running at once. `Retry-After` says how long to
        wait.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
            examples:
              - 45
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            rate_limit_exceeded:
              value:
                success: false
                error: rate_limit_exceeded
                message: Rate limit exceeded. Please retry after 45 seconds.
                retry_after: 45
                limits:
                  per_minute: 150
                  per_day: 5000
                  current_minute: 150
                  current_day: 3204
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Your API key, from the [API
        Panel](https://bouncewatch.com/api-panel/api-keys).

````