Bulk Lookup Job Results

Retrieve lookup results for a bulk job. Paginated; each row mirrors the /v1/email-lookup response shape.

GET /v1/bulk-lookup/{job_id}/results

Get Bulk Lookup Results

cURL

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

200

{
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "limit": 50,
  "offset": 0,
  "results": [],
  "total_processed": 500,
  "total_rows": 500
}

Use this endpoint to retrieve the lookup results for a bulk job. The response contains a results array — one object per row processed so far — alongside paging metadata (limit, offset, total_rows, total_processed).

You can call this endpoint while the job is still running to retrieve partial results. The total_processed field tells you how many rows have been completed at the time of the call.

Pagination

Results are paginated with limit and offset query parameters:

Parameter	Default	Maximum	Notes
limit	50	500	Number of rows to return in this page.
offset	0	—	Index into the ordered result set.

To page through a complete job, increment offset by limit until the returned results array is empty (or offset >= total_rows).

Per-row shape

Each entry in results is identical in shape to the POST /v1/email-lookup response — same status, substatus, email, enrichment fields, and the echoed first_name, last_name, domain from your input.

Outcome	status	substatus	email	confidence	credits_consumed
Found	safe	deliverable	the discovered address	0–100	1
Not found	unknown	no_address_found	null	null	1

For not_found rows, the enrichment fields (email_provider, mx_record, is_* flags, confidence) may be null or "Unknown" — they’re populated only when a deliverable address is returned. See the response schema for field-by-field details.

Example response

{
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_rows": 500,
  "total_processed": 500,
  "limit": 50,
  "offset": 0,
  "results": [
    {
      "email": "[e-mail]",
      "status": "safe",
      "substatus": "deliverable",
      "explanation": "Safe to email. The mailbox exists and is deliverable.",
      "email_provider": "Google Workspace",
      "mx_record": "aspmx.l.google.com",
      "is_domain_catch_all": false,
      "is_secure_email_gateway": false,
      "is_disposable": false,
      "is_role_account": false,
      "is_free": false,
      "credits_consumed": 1,
      "first_name": "Jane",
      "last_name": "Doe",
      "domain": "acme.com",
      "confidence": 99
    },
    {
      "email": null,
      "status": "unknown",
      "substatus": "no_address_found",
      "explanation": "No deliverable address could be found for the given name at this domain.",
      "email_provider": "Unknown",
      "mx_record": null,
      "is_domain_catch_all": null,
      "is_secure_email_gateway": false,
      "is_disposable": null,
      "is_role_account": null,
      "is_free": null,
      "credits_consumed": 1,
      "first_name": "John",
      "last_name": "Smith",
      "domain": "bigcorp.io",
      "confidence": null
    }
  ]
}

Authorizations

X-API-Key · string · header · required

API key for authentication

Path Parameters

job_id · string · required

Query Parameters

limit · integer · default: 50

offset · integer · default: 0

Response

200

application/json

Successful Response

Paginated results for a bulk lookup job.

job_id · string<uuid> · required

Unique job identifier.

Example:

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

total_rows · integer · required

Total rows submitted.

Example:

500

total_processed · integer · required

Rows processed so far.

Example:

500

limit · integer · required

Page size used for this response.

Example:

50

offset · integer · required

Row offset into the ordered result set.

Example:

0

results · EmailLookupResponse · object[] · required

Per-row lookup results, one object per submitted tuple.

Show child attributes