Bulk search

POST

bulk

Submit a bulk search job

curl --request POST \
  --url https://api.orbitsearch.com/v3/search/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "request_id": "<string>",
  "items": [
    {
      "query": "Machine learning engineers at Anthropic near San Francisco",
      "intent": {
        "experiences": [
          {
            "titleAnyOf": [
              "Research Engineer",
              "ML Engineer"
            ],
            "organization": "Anthropic",
            "temporalScope": "current"
          }
        ],
        "geo": {
          "distance": "25 miles"
        }
      },
      "candidate_discovery": true,
      "profile_depth": "partial",
      "include_profile": true,
      "limit": 10,
      "id": "search-ml-sf-001"
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    request_id: '<string>',
    items: [
      {
        query: 'Machine learning engineers at Anthropic near San Francisco',
        intent: {
          experiences: [
            {
              titleAnyOf: ['Research Engineer', 'ML Engineer'],
              organization: 'Anthropic',
              temporalScope: 'current'
            }
          ],
          geo: {distance: '25 miles'}
        },
        candidate_discovery: true,
        profile_depth: 'partial',
        include_profile: true,
        limit: 10,
        id: 'search-ml-sf-001'
      }
    ]
  })
};

fetch('https://api.orbitsearch.com/v3/search/bulk', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.orbitsearch.com/v3/search/bulk"

payload = {
    "request_id": "<string>",
    "items": [
        {
            "query": "Machine learning engineers at Anthropic near San Francisco",
            "intent": {
                "experiences": [
                    {
                        "titleAnyOf": ["Research Engineer", "ML Engineer"],
                        "organization": "Anthropic",
                        "temporalScope": "current"
                    }
                ],
                "geo": { "distance": "25 miles" }
            },
            "candidate_discovery": True,
            "profile_depth": "partial",
            "include_profile": True,
            "limit": 10,
            "id": "search-ml-sf-001"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "request_id": "<string>",
  "status": "queued",
  "cancel_requested": true,
  "counts": {
    "total": 1,
    "completed": 1,
    "failed": 1,
    "canceled": 1,
    "pending": 1
  },
  "billing": {
    "consumed_credits": 1,
    "held_credits": 1
  },
  "last_error": {
    "code": "<string>",
    "message": "<string>"
  },
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "links": {
    "status": "<string>",
    "results": "<string>",
    "cancel": "<string>"
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

Submit a list of searches once, then poll one job. Orbit queues the work and retries temporary processing failures automatically. You do not need to send or retry a separate HTTP request for every CSV row. Requires search:read. Items with include_profile: true also require profile:read when submitting and reading results.

curl -X POST "https://api.orbitsearch.com/v3/search/bulk" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "contacts-import-2026-09-15",
    "items": [
      {
        "id": "csv-row-2",
        "signals": { "email": "person@example.com" },
        "limit": 1,
        "candidate_discovery": true,
        "candidate_discovery_limit": 1,
        "profile_depth": "partial",
        "include_profile": false
      }
    ]
  }'

Each item has a unique id and the fields from Search, except request_id. Put request_id on the whole job. Face searches use the individual Search endpoint.

Submit and retry

A successful submission returns 202 with job_id, request_id, status, counts, billing, and links to status, results, and cancellation. Keep the same request_id when retrying submission. With the same API key, normalized items, and search-session context, it returns the original job. Changing the items or adding, removing, or changing the signed-in session under that identity returns 409 bulk_search_idempotency_conflict. Limits:

1–5,000 items per job and an 8 MiB request body.
At most 32 KiB per item.
request_id and item id values must contain 1–128 characters.
At most four unfinished jobs per billing account.

A full queue returns 409 bulk_search_queue_full with Retry-After. Retry the same job identity after the indicated delay. An accepted job does not consume the individual Search request-rate allowance for every item. Submission and cancellation each allow a burst of eight HTTP requests per API key, refilling at one request every two seconds. Status and results share a separate bucket with a burst of 30, refilling at five requests per second. Excessive requests return 429 with Retry-After; accepted jobs keep processing. These buckets are separate from individual Search. When submitting with an authenticated search session, use the same signed-in person for status, results, cancellation, and idempotent replay. Directory access is checked again during processing and result reads.

Track progress

GET /v3/search/bulk/{job_id}

Poll about every three seconds. Job statuses are queued, running, waiting_for_credits, needs_attention, completed, completed_with_errors, and canceled. counts includes total, completed, failed, canceled, and pending. Failed counts include items that completed with some errors. An empty successful search is completed; it is not a processing failure. Temporary errors appear in last_error while the job retries. If the job enters waiting_for_credits, add credits to the same billing account. It resumes automatically. After repeated recovery failures, needs_attention asks you to contact support with the job id. Automatic recovery continues about every five minutes. Started work and its reserved credits remain tracked until their outcome is established.

Read results

GET /v3/search/bulk/{job_id}/results?offset=0

Each page contains at most ten items and a next_offset. The offset follows the original input order, including unfinished items. Revisit unfinished pages after the job advances. Each item includes:

id: your original item id.
index: its zero-based position.
status: queued, processing, completed, completed_with_errors, failed, or canceled.
result: a v3 search snapshot, or null until its results are ready to publish.

Use the result’s status link to return to that item’s bulk results page. Its internal search identifier does not create an independently pollable Search resource. Search confidence, candidate-discovery behavior, and profile depth have the same meanings as in an individual v3 search. Results become available in small groups after their billing completes. A slow item can delay publication of the other items in its group.

Billing and cancellation

Credits are reserved as groups of items begin processing. Orbit charges for the results under the v3 pricing rules and releases unused credits. Retrying a job or reading its saved results does not repeat its search charges. Different item ids represent separate searches, even if their inputs are identical.

POST /v3/search/bulk/{job_id}/cancel

Cancellation skips undispatched items. Work that already started finishes reconciling and billing, so cancellation can remain pending while that work completes. Published results stay available.

Authorizations

Authorization

string

header

required

Use an Orbit API key from the developer dashboard.

Body

application/json

request_id

string

required

Required string length: 1 - 128

items

object[]

required

Required array length: 1 - 5000 elements

Provide query, intent, at least one identity signal, or a supported combination. When query and intent are both present, Orbit derives a base intent from query and overlays the caller-provided intent. Arrays, scalar values, and null replace derived values; nested objects merge field by field.

Option 1
Option 2
Option 3

Show child attributes

Example:

{
  "query": "Machine learning engineers at Anthropic near San Francisco",
  "intent": {
    "experiences": [
      {
        "titleAnyOf": ["Research Engineer", "ML Engineer"],
        "organization": "Anthropic",
        "temporalScope": "current"
      }
    ],
    "geo": { "distance": "25 miles" }
  },
  "candidate_discovery": true,
  "profile_depth": "partial",
  "include_profile": true,
  "limit": 10,
  "id": "search-ml-sf-001"
}

Response

Bulk search response.

job_id

string<uuid>

required

request_id

string

required

status

enum<string>

required

Available options:

queued,

running,

waiting_for_credits,

needs_attention,

completed,

completed_with_errors,

canceled

cancel_requested

boolean

required

counts

object

required

Show child attributes

billing

object

required

Show child attributes

last_error

object | null

required

Show child attributes

created_at

string<date-time>

required

updated_at

string<date-time>

required

links

object

required

Show child attributes

Submit a bulk search job

curl --request POST \
  --url https://api.orbitsearch.com/v3/search/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "request_id": "<string>",
  "items": [
    {
      "query": "Machine learning engineers at Anthropic near San Francisco",
      "intent": {
        "experiences": [
          {
            "titleAnyOf": [
              "Research Engineer",
              "ML Engineer"
            ],
            "organization": "Anthropic",
            "temporalScope": "current"
          }
        ],
        "geo": {
          "distance": "25 miles"
        }
      },
      "candidate_discovery": true,
      "profile_depth": "partial",
      "include_profile": true,
      "limit": 10,
      "id": "search-ml-sf-001"
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    request_id: '<string>',
    items: [
      {
        query: 'Machine learning engineers at Anthropic near San Francisco',
        intent: {
          experiences: [
            {
              titleAnyOf: ['Research Engineer', 'ML Engineer'],
              organization: 'Anthropic',
              temporalScope: 'current'
            }
          ],
          geo: {distance: '25 miles'}
        },
        candidate_discovery: true,
        profile_depth: 'partial',
        include_profile: true,
        limit: 10,
        id: 'search-ml-sf-001'
      }
    ]
  })
};

fetch('https://api.orbitsearch.com/v3/search/bulk', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.orbitsearch.com/v3/search/bulk"

payload = {
    "request_id": "<string>",
    "items": [
        {
            "query": "Machine learning engineers at Anthropic near San Francisco",
            "intent": {
                "experiences": [
                    {
                        "titleAnyOf": ["Research Engineer", "ML Engineer"],
                        "organization": "Anthropic",
                        "temporalScope": "current"
                    }
                ],
                "geo": { "distance": "25 miles" }
            },
            "candidate_discovery": True,
            "profile_depth": "partial",
            "include_profile": True,
            "limit": 10,
            "id": "search-ml-sf-001"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "request_id": "<string>",
  "status": "queued",
  "cancel_requested": true,
  "counts": {
    "total": 1,
    "completed": 1,
    "failed": 1,
    "canceled": 1,
    "pending": 1
  },
  "billing": {
    "consumed_credits": 1,
    "held_credits": 1
  },
  "last_error": {
    "code": "<string>",
    "message": "<string>"
  },
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "links": {
    "status": "<string>",
    "results": "<string>",
    "cancel": "<string>"
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

Search

Enrich

Watchers

Webhooks

Keys

Submit and retry

Track progress

Read results

Billing and cancellation

Authorizations

Body

Response

​Submit and retry

​Track progress

​Read results

​Billing and cancellation

Authorizations

Body

Response

Submit and retry

Track progress

Read results

Billing and cancellation