Bulk Lookup Job Status

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

GET /v1/bulk-lookup/{job_id}

Get Bulk Lookup Status

cURL

curl --request GET \
  --url https://api.orbisearch.com/v1/bulk-lookup/{job_id} \
  --header 'X-API-Key: <api-key>'

200

{
  "created_at": "2026-04-21T14:30:00Z",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "running",
  "summary": {
    "total_found": 198,
    "total_not_found": 39
  },
  "total_processed": 237,
  "total_rows": 500
}

Use this endpoint to check the progress of a bulk lookup job. Poll it periodically after submitting via POST /v1/bulk-lookup to determine when your results are ready. The response tells you how many rows have been processed, the current job status, and a per-outcome summary.

Job status values

Status	Meaning
running	Job is still processing rows. Continue polling.
completed	All rows have been processed. Results are ready to retrieve.

Outcome summary

The summary object on the response gives a per-outcome breakdown that updates as the job progresses:

Field	Meaning
total_found	Rows where a deliverable email was found.
total_not_found	Rows where no deliverable address was found at the domain.

Every row in either bucket is charged 1 credit. total_found + total_not_found equals total_processed.

Polling cadence

For most jobs, polling every 10–30 seconds is sufficient. 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).

Authorizations

X-API-Key · string · header · required

API key for authentication

Path Parameters

job_id · string · required

Response

200

application/json

Successful Response

Status snapshot of a bulk lookup job.

job_id · string<uuid> · required

Unique job identifier.

Example:

"123e4567-e89b-12d3-a456-426614174000"

status · enum<string> · required

Job status: running (still processing) or completed (all rows done).

Available options: running, completed

Example:

"running"

total_rows · integer · required

Total rows submitted.

Example:

500

total_processed · integer · required

Rows processed so far.

Example:

237

summary · BulkLookupSummary · object · required

Per-outcome counts.

Show child attributes

created_at · string · required

Job submission timestamp (UTC).

Example:

"2026-04-21T14:30:00Z"

finished_at · string | null

Timestamp of the last processed row (UTC). Null while running.

Example:

null