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

# Bulk Company Enrichment Job Status

> Check the status and progress of a bulk company enrichment job. Returns the current status, per-outcome counts, and row totals.

Use this endpoint to check the progress of a bulk company enrichment job. Poll it periodically after submitting via [POST /v1/company-enrichment/bulk](/docs/api-reference/company-enrichment-bulk-submit) to determine when your results are ready. The response tells you how many rows have been answered, the current job status, and a per-outcome summary.

## Job status values

| Status | Meaning |
| - | - |
| `running` | Job is still processing rows. Continue polling. |
| `completed` | Every row has been answered. Results are ready to retrieve. |

## Outcome summary

The `summary` object on the response gives a per-outcome breakdown that updates as the job progresses. Counts are in submitted rows, so duplicates are counted each time they appear:

| Field | Meaning |
| - | - |
| `total_found` | Rows where a company record was returned. |
| `total_not_found` | Rows with a valid company URL that matches no company. |
| `total_error` | Rows OrbiSearch couldn't answer. |
| `total_invalid_url` | Rows skipped at submission because they weren't a usable company URL. These cost nothing. |

`credits_consumed` is the amount charged when the job was submitted. It doesn't change as the job runs.

## Polling cadence

For most jobs, polling every 10–30 seconds is sufficient. Even a small job can take up to a minute to complete. Polling more frequently than necessary won't speed up processing and counts against your rate limit (`20` requests per second per API key, shared across the `/v1/*` API).


## OpenAPI

````yaml GET /v1/company-enrichment/bulk/{job_id}
openapi: 3.1.0
info:
  title: OrbiSearch Public API
  version: 1.0.0
  description: >-
    Email verification API for developers and agents. [Get your API key
    →](https://orbisearch.com/dashboard/api-keys)


    **Rate limiting:** requests are limited per API key (20 requests per second
    by default). Every response includes `X-RateLimit-Limit`,
    `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers describing the
    current per-key window so clients can self-throttle; `429` responses also
    include a `Retry-After` header with the suggested backoff in seconds.
  contact:
    name: Get API Key
    url: https://orbisearch.com/dashboard/api-keys
servers:
  - url: https://api.orbisearch.com
    description: OrbiSearch Public API
security:
  - ApiKeyAuth: []
paths:
  /v1/company-enrichment/bulk/{job_id}:
    get:
      tags:
        - Public API v1
      summary: Get Company Enrichment Bulk Status
      description: |-
        Check the status and progress of a bulk company-enrichment job. Returns
        the current `status` (`running` or `completed`), per-outcome counts, and
        row totals. Poll until `status=completed`, then fetch results.
      operationId: >-
        get_company_enrichment_bulk_status_v1_company_enrichment_bulk__job_id__get
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyBulkStatusResponse'
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              example:
                detail: API key required in X-API-Key header
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Job not found or does not belong to this API key
          content:
            application/json:
              example:
                detail: Job not found
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
        '422':
          description: Invalid request parameters
          content:
            application/json:
              example:
                detail: 'Missing required query parameter: email.'
                errors:
                  - loc: query.email
                    msg: 'Missing required query parameter: email.'
                    type: missing
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: >-
                Seconds the client should wait before retrying. Computed from
                the remaining rate-limit window (typically 1 for the per-second
                limit, longer when the limit is exceeded by 3x or more); for
                endpoints with a daily quota, seconds until the quota resets.
              schema:
                type: integer
                examples:
                  - 1
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
          content:
            application/json:
              example:
                detail: >-
                  Rate limit exceeded. Maximum 20 requests per second per API
                  key. Contact us to discuss higher limits.
                code: rate_limited
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CompanyBulkStatusResponse:
      properties:
        job_id:
          type: string
          format: uuid
          title: Job Id
          description: Unique job identifier.
        status:
          type: string
          enum:
            - running
            - completed
          title: Status
          description: 'Job status: running (still processing) or completed (all rows done).'
          examples:
            - running
        total_rows:
          type: integer
          title: Total Rows
          description: >-
            Total input rows submitted (repeats included; unique companies are
            what was charged).
          examples:
            - 500
        total_processed:
          type: integer
          title: Total Processed
          description: Input rows answered so far.
          examples:
            - 237
        credits_consumed:
          type: number
          title: Credits Consumed
          description: >-
            Credits deducted for this job: 1 credit per distinct input, charged
            once at submit and never refunded after acceptance. Failed rows stay
            charged; invalid rows were never charged.
          examples:
            - 490
        summary:
          $ref: '#/components/schemas/CompanyBulkSummary'
          description: Per-outcome counts.
        created_at:
          type: string
          title: Created At
          description: Job submission timestamp (UTC).
        finished_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Finished At
          description: Timestamp of the last processed row (UTC). Null while running.
      type: object
      required:
        - job_id
        - status
        - total_rows
        - total_processed
        - credits_consumed
        - summary
        - created_at
      title: CompanyBulkStatusResponse
      description: Status snapshot of a bulk company-enrichment job.
      example:
        job_id: 123e4567-e89b-12d3-a456-426614174000
        status: running
        total_rows: 500
        total_processed: 237
        credits_consumed: 490
        summary:
          total_found: 198
          total_not_found: 29
          total_error: 10
          total_invalid_url: 5
        created_at: '2026-09-25T14:30:00Z'
    ApiErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Human-readable description of what went wrong.
          examples:
            - API key required in X-API-Key header
        code:
          anyOf:
            - type: string
            - type: 'null'
          title: Code
          description: >-
            Stable machine-readable error code, present on conditions a client
            may want to branch on (for example `rate_limited` for the per-second
            limit versus `daily_quota_exceeded` for the daily cap). Absent on
            errors that need no further disambiguation.
          examples:
            - daily_quota_exceeded
        errors:
          anyOf:
            - items:
                $ref: '#/components/schemas/ValidationErrorDetail'
              type: array
            - type: 'null'
          title: Errors
          description: >-
            Individual validation failures, one entry per invalid parameter or
            field. Present only on 422 responses; when the request has a single
            problem, `detail` carries the same message. Absent on all other
            error codes.
      type: object
      required:
        - detail
      title: ApiErrorResponse
      description: Error response body.
    CompanyBulkSummary:
      properties:
        total_found:
          type: integer
          title: Total Found
          description: Input rows where a company record was returned (repeats included).
          examples:
            - 420
        total_not_found:
          type: integer
          title: Total Not Found
          description: >-
            Input rows that were read (a company URL or a website domain) but no
            company matches them (repeats included).
          examples:
            - 70
        total_error:
          type: integer
          title: Total Error
          description: Input rows our infrastructure could not answer (repeats included).
          examples:
            - 10
        total_invalid_url:
          type: integer
          title: Total Invalid Url
          description: >-
            Input rows skipped at submit (a numeric-ID or malformed URL, a name
            over 200 characters, a domain cell that is not a website domain, or
            a blank row), repeats included. Counted as processed and charged
            nothing.
          examples:
            - 10
      type: object
      required:
        - total_found
        - total_not_found
        - total_error
        - total_invalid_url
      title: CompanyBulkSummary
      description: Per-outcome counts for a bulk company-enrichment job.
    ValidationErrorDetail:
      properties:
        loc:
          type: string
          title: Loc
          description: >-
            Where in the request the problem is, as a dot-separated path (e.g.
            `query.email`, `body.0`).
          examples:
            - query.email
        msg:
          type: string
          title: Msg
          description: Human-readable description of this validation error.
          examples:
            - 'Missing required query parameter: email.'
        type:
          type: string
          title: Type
          description: >-
            Machine-readable error category (e.g. `missing`, `less_than_equal`,
            `string_too_long`).
          examples:
            - missing
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationErrorDetail
      description: One request-validation failure.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: API key for authentication
      in: header
      name: X-API-Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.