Get search status

GET

{search_id}

Get search status

curl --request GET \
  --url https://api.orbitsearch.com/v3/search/{search_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

{
  "search_id": "<string>",
  "request_id": "<string>",
  "status": "running",
  "candidate_discovery": true,
  "profile_depth": "partial",
  "include_profile": true,
  "profile_upgrades_completed": true,
  "results": [
    {
      "profile_id": "<string>",
      "status": "generating",
      "generation_level": 2,
      "sources": [
        "search"
      ],
      "candidate_sources": [
        {
          "link": "<string>",
          "title": "<string>",
          "sourceImage": "<string>"
        }
      ],
      "preview": {},
      "profile": {
        "id": "<string>",
        "generationLevel": 2,
        "avatarUrl": "<string>",
        "verified": true,
        "sections": {},
        "sources": [
          {
            "link": "<string>",
            "title": "<string>",
            "summary": "<string>",
            "caption": "<string>",
            "images": [
              "<string>"
            ],
            "sourceName": "<string>",
            "sourceImage": "<string>",
            "chunks": [
              {
                "text": "<string>"
              }
            ],
            "sources": "<array>"
          }
        ],
        "displayName": "<string>",
        "personName": "<string>",
        "aliases": [
          "<string>"
        ],
        "profileUrl": "<string>",
        "slug": "<string>",
        "category": {
          "id": "<string>",
          "label": "<string>"
        },
        "location": {
          "city": "<string>",
          "region": "<string>",
          "country": "<string>"
        },
        "headline": {
          "jobTitle": "<string>",
          "companyName": "<string>",
          "schoolName": "<string>"
        },
        "emails": [
          "jsmith@example.com"
        ],
        "phoneNumbers": [
          "<string>"
        ],
        "addresses": [
          {}
        ]
      },
      "failure": {
        "code": "<string>",
        "message": "<string>",
        "retryable": true,
        "reason": "<string>",
        "suggested_inputs": [
          "<string>"
        ]
      }
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "links": {
    "status": "<string>"
  },
  "candidate_discovery_completed": true,
  "discovered_sources": [
    {
      "link": "<string>",
      "title": "<string>",
      "sourceImage": "<string>"
    }
  ],
  "candidate_discovery_failure": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "reason": "<string>",
    "suggested_inputs": [
      "<string>"
    ]
  }
}

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

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

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

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

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

Returns the latest search snapshot. Polling this endpoint advances pending discovery and profile work before returning the response.

curl "https://api.orbitsearch.com/v3/search/$SEARCH_ID" \
  -H "Authorization: Bearer $ORBIT_API_KEY"

Parameter	Location	Required	Description
`search_id`	path	Yes	The `search_id` returned by `POST /v3/search`.

The response has the same shape as Start a search. Every result includes sources containing search, candidate_discovery, or both. Known-search results retain their lightweight preview on every poll, regardless of include_profile. When include_profile is true, every poll also embeds the latest readable canonical profile, including a level 1 profile while that result is still enriching.

Know when a search is done

status answers one question: is the whole search done, and how did it go? Continue polling while it is running. Stop when it becomes:

completed: every result reached the requested profile_depth. A search can also complete with an empty results list when nothing matched.
completed_with_errors: ready results are available, but at least one result or candidate discovery failed.
failed: work failed and the search has no ready results.

A search completes when every result is published at the requested depth. Orbit can continue to improve published profiles afterward, so a later profile read can return more data than the search response embedded.

Track each phase

Two snapshot fields report the search’s phases independently:

candidate_discovery_completed answers: is the result list final? When true, discovery adds no more results to this search. For discovery searches it becomes true as soon as clustering fixes the candidate set and every discovered person appears in results — usually while those results are still generating. Present only when the search ran with candidate_discovery: true. If discovery failed, candidate_discovery_failure explains why.
profile_upgrades_completed answers: are the current profiles final? When true, every result currently in results reached the requested profile_depth or failed. While candidate_discovery_completed is false, discovery can still add results that bring new profile work.

Poll on status alone — it is the only signal that the search is finished. Use these fields to show progress. For a discovery search, candidate_discovery_completed: true with profile_upgrades_completed: false is the normal mid-run state: all people are found and their profiles are still building, so you can render the final list of people while their profiles fill in.

Result statuses

Each entry in results moves through its own lifecycle, separate from the search status:

Status	Meaning
`generating`	Candidate discovery found this person and is building their first profile. No readable profile exists yet and `generation_level` is `null`. The result can already carry `preview` and `candidate_sources`. This status appears only on candidate discovery results, so searches without `candidate_discovery: true` never produce it.
`enriching`	A profile exists and can be read at its current depth, but it is below the requested `profile_depth`. Orbit is building it up.
`ready`	The profile reached the requested `profile_depth`. With `include_profile: true`, the result embeds the `profile` object.
`failed`	This result cannot reach the requested depth. `failure` contains a machine-readable reason. A failed result does not block other results.

Statuses only move forward: generating becomes enriching, enriching becomes ready or failed, and ready never regresses.

Result stability

Snapshots are stable between polls:

A result never disappears from a later response. New candidate results append after the existing rows.
limit caps only the initial matches from the existing Orbit index. Candidate Discovery results append outside that quota, and profile upgrades update rows in place. The final results count can therefore exceed limit and has no fixed multiple of it.

Key your UI by profile_id and update rows in place. You can render ready results while the rest of the search is still running.

async function waitForSearch(searchId) {
  while (true) {
    const response = await fetch(
      `https://api.orbitsearch.com/v3/search/${searchId}`,
      { headers: { Authorization: `Bearer ${process.env.ORBIT_API_KEY}` } }
    );
    const search = await response.json();

    if (search.status !== "running") return search;
    await new Promise((resolve) => setTimeout(resolve, 1500));
  }
}

During candidate discovery, the polling response includes pending and assigned source receipts:

{
  "discovered_sources": [
    {
      "link": "https://example.org/ml-engineers",
      "title": "Machine learning engineers",
      "sourceImage": "https://example.org/favicon.ico"
    }
  ],
  "results": [
    {
      "profile_id": "profile_456",
      "status": "enriching",
      "generation_level": 1,
      "sources": ["candidate_discovery"],
      "candidate_sources": [
        {
          "link": "https://example.com/team",
          "title": "Example team",
          "sourceImage": "https://example.com/favicon.ico"
        }
      ]
    },
    {
      "profile_id": "profile_789",
      "status": "generating",
      "generation_level": null,
      "sources": ["candidate_discovery"],
      "preview": {
        "id": "profile_789",
        "displayName": "Example Candidate",
        "city": "San Francisco"
      }
    }
  ]
}

discovered_sources starts filling within seconds of the search starting, while Orbit is still gathering, and decreases as Orbit assigns sources to candidates. The assigned receipts appear in results[].candidate_sources and remain there when the result becomes ready. Every receipt contains link, title, and sourceImage. results[].sources is the existing result-origin list and does not contain source receipts. In both receipt arrays, link is the URL of the discovered source page, title is the display title of the source page or site, and sourceImage is the URL of the favicon for the site that hosts the source page. This endpoint requires search:read. If the original search used include_profile: true, the caller also needs profile:read. A search is only visible to the API key that created it.

Authorizations

Authorization

string

header

required

Use an Orbit API key from the developer dashboard.

Path Parameters

search_id

string

required

The search ID returned by POST /v3/search.

Minimum string length: 1

Response

The current search snapshot.

search_id

string

required

Server-generated identifier for this search. Use it to poll the status endpoint.

request_id

string

required

The idempotency key from the original request, or a generated value when the request omitted it.

status

enum<string>

required

Overall search lifecycle. running means work is still in progress; poll until the status is terminal. completed means every result reached the requested profile depth; a search can complete with an empty results list when nothing matched. completed_with_errors means ready results are available but some work failed. failed means work failed and no ready results are available.

Available options:

running,

completed,

completed_with_errors,

failed

candidate_discovery

boolean

required

Whether this search runs candidate discovery, as resolved from the request.

profile_depth

enum<string>

required

The minimum profile depth requested for each ready result.

Available options:

partial,

full

include_profile

boolean

required

Whether ready results embed the full profile object.

profile_upgrades_completed

boolean

required

Whether every result in results has reached the requested profile_depth or failed. While candidate_discovery_completed is false, discovery can still add results with new profile work.

results

object[]

required

The people this search has found so far. Results are append-only: a reported result is never removed, and a ready result never regresses.

Show child attributes

created_at

string<date-time>

required

When the search was created.

updated_at

string<date-time>

required

When the snapshot last changed.

links

object

required

Show child attributes

candidate_discovery_completed

boolean

Whether the result list is final. Once true, discovery adds no more results to this search; the results themselves can still be generating or enriching toward the requested depth. For discovery searches this becomes true when clustering completes and every discovered person appears in results. If discovery failed, candidate_discovery_failure explains why. Present only when candidate_discovery is true.

discovered_sources

object[]

Candidate Discovery source receipts that have not yet been assigned to a result. Present when candidate_discovery is true.

Show child attributes

candidate_discovery_failure

object

Why candidate discovery failed. Present only when discovery failed.

Show child attributes

Get search status

curl --request GET \
  --url https://api.orbitsearch.com/v3/search/{search_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

{
  "search_id": "<string>",
  "request_id": "<string>",
  "status": "running",
  "candidate_discovery": true,
  "profile_depth": "partial",
  "include_profile": true,
  "profile_upgrades_completed": true,
  "results": [
    {
      "profile_id": "<string>",
      "status": "generating",
      "generation_level": 2,
      "sources": [
        "search"
      ],
      "candidate_sources": [
        {
          "link": "<string>",
          "title": "<string>",
          "sourceImage": "<string>"
        }
      ],
      "preview": {},
      "profile": {
        "id": "<string>",
        "generationLevel": 2,
        "avatarUrl": "<string>",
        "verified": true,
        "sections": {},
        "sources": [
          {
            "link": "<string>",
            "title": "<string>",
            "summary": "<string>",
            "caption": "<string>",
            "images": [
              "<string>"
            ],
            "sourceName": "<string>",
            "sourceImage": "<string>",
            "chunks": [
              {
                "text": "<string>"
              }
            ],
            "sources": "<array>"
          }
        ],
        "displayName": "<string>",
        "personName": "<string>",
        "aliases": [
          "<string>"
        ],
        "profileUrl": "<string>",
        "slug": "<string>",
        "category": {
          "id": "<string>",
          "label": "<string>"
        },
        "location": {
          "city": "<string>",
          "region": "<string>",
          "country": "<string>"
        },
        "headline": {
          "jobTitle": "<string>",
          "companyName": "<string>",
          "schoolName": "<string>"
        },
        "emails": [
          "jsmith@example.com"
        ],
        "phoneNumbers": [
          "<string>"
        ],
        "addresses": [
          {}
        ]
      },
      "failure": {
        "code": "<string>",
        "message": "<string>",
        "retryable": true,
        "reason": "<string>",
        "suggested_inputs": [
          "<string>"
        ]
      }
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "links": {
    "status": "<string>"
  },
  "candidate_discovery_completed": true,
  "discovered_sources": [
    {
      "link": "<string>",
      "title": "<string>",
      "sourceImage": "<string>"
    }
  ],
  "candidate_discovery_failure": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "reason": "<string>",
    "suggested_inputs": [
      "<string>"
    ]
  }
}

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

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

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

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

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

Search

Enrich

Watchers

Webhooks

Keys

Know when a search is done

Track each phase

Result statuses

Result stability

Authorizations

Path Parameters

Response

​Know when a search is done

​Track each phase

​Result statuses

​Result stability

Authorizations

Path Parameters

Response

Know when a search is done

Track each phase

Result statuses

Result stability