Bulk Lookup Job Status

GET

bulk-lookup

{job_id}

Get Bulk Lookup Status

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

import requests

url = "https://api.orbisearch.com/v1/bulk-lookup/{job_id}"

headers = {"X-API-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.orbisearch.com/v1/bulk-lookup/{job_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.orbisearch.com/v1/bulk-lookup/{job_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.orbisearch.com/v1/bulk-lookup/{job_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.orbisearch.com/v1/bulk-lookup/{job_id}")
  .header("X-API-Key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.orbisearch.com/v1/bulk-lookup/{job_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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
}

{
  "detail": "API key required in X-API-Key header"
}

{
  "detail": "Job not found"
}

{
  "detail": "Missing required query parameter: email.",
  "errors": [
    {
      "loc": "query.email",
      "msg": "Missing required query parameter: email.",
      "type": "missing"
    }
  ]
}

{
  "detail": "Rate limit exceeded. Maximum 20 requests per second per API key. Contact us to discuss higher limits.",
  "code": "rate_limited"
}

{
  "detail": "Email lookup is not available in this environment"
}

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

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

Submit Bulk Lookup Job

Bulk Lookup Job Results

Get Bulk Lookup Status

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

import requests

url = "https://api.orbisearch.com/v1/bulk-lookup/{job_id}"

headers = {"X-API-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.orbisearch.com/v1/bulk-lookup/{job_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.orbisearch.com/v1/bulk-lookup/{job_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.orbisearch.com/v1/bulk-lookup/{job_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.orbisearch.com/v1/bulk-lookup/{job_id}")
  .header("X-API-Key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.orbisearch.com/v1/bulk-lookup/{job_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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
}

{
  "detail": "API key required in X-API-Key header"
}

{
  "detail": "Job not found"
}

{
  "detail": "Missing required query parameter: email.",
  "errors": [
    {
      "loc": "query.email",
      "msg": "Missing required query parameter: email.",
      "type": "missing"
    }
  ]
}

{
  "detail": "Rate limit exceeded. Maximum 20 requests per second per API key. Contact us to discuss higher limits.",
  "code": "rate_limited"
}

{
  "detail": "Email lookup is not available in this environment"
}

Email validation

Email finder

Deliverability

Account

Reference

Bulk Lookup Job Status

Job status values

Outcome summary

Polling cadence

Authorizations

Path Parameters

Response

​Job status values

​Outcome summary

​Polling cadence

Authorizations

Path Parameters

Response

Job status values

Outcome summary

Polling cadence