Skip to main content
The Orbit Search API lets you query a global index of public professional profiles using natural-language queries. This guide walks you through every step: getting an API key, running your first search request, reading the response, and fetching a complete profile for any result you get back.

​
Prerequisites

You need an active Orbit account. All requests require a Bearer token in the Authorization header and use the API base URL https://api.orbitsearch.com.

​
Steps

1

Get an API key

Open the Orbit developer dashboard and generate a personal API key with the search:read and profile:read scopes. Copy the raw sk_orb_... key when it appears.
export ORBIT_API_KEY="sk_orb_REDACTED"
The public API starts after key issuance. Store the raw key in a secure location before closing the dashboard modal; it is not shown again.
2

Run a global search

Send a POST request to the developer search endpoint. The query and numUsers fields are both required.
curl -X POST "https://api.orbitsearch.com/v2/developer/search" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query": "founders in sf", "numUsers": 10}'
Always pass an Idempotency-Key header — a unique string such as a UUID — on every search request. If your request times out and you retry, the server uses this key to avoid double-charging your credits. Without it, the server falls back to a per-request ID that cannot deduplicate retries across separate HTTP connections.
3

Interpret the search response

A successful search returns a searchId and a payload.users array. The array may be empty if the index found no matching profiles for your query.
{
  "status": "success",
  "searchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "payload": {
    "users": [
      {
        "id": "profile_a1b2c3d4e5f6",
        "displayName": "Ada Lovelace",
        "headline": "Founder at Example Co"
      }
    ]
  }
}
Check the X-Developer-API-Credits-Remaining response header to see how many credits you have left after the request. Each successful search costs 2 credits by default. If the search returns no users, the credits are automatically refunded and the header will reflect your full balance.Each object in payload.users contains an id field. Use this to fetch a full profile in the next step.
4

Fetch a full profile

Pass the id from any search result to GET /v2/developer/profiles/:id to retrieve the complete public profile DTO.
# Extract the profile id from the first search result and fetch its profile
SEARCH_RESPONSE=$(
  curl -s -X POST "https://api.orbitsearch.com/v2/developer/search" \
    -H "Authorization: Bearer $ORBIT_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "founders in sf", "numUsers": 10}'
)

PROFILE_ID=$(echo "$SEARCH_RESPONSE" | jq -r '.payload.users[0].id')

curl "https://api.orbitsearch.com/v2/developer/profiles/$PROFILE_ID" \
  -H "Authorization: Bearer $ORBIT_API_KEY"
A successful profile read returns a stable public profile DTO:
{
  "status": "success",
  "payload": {
    "id": "orbit-profile-id",
    "displayName": "Ada Lovelace",
    "personName": "Ada Lovelace",
    "aliases": ["Ada Byron", "Countess Ada"],
    "avatarUrl": "https://...",
    "profileUrl": "https://orbitsearch.com/ada",
    "verified": true,
    "location": {
      "city": "San Francisco, CA, US"
    },
    "headline": {
      "jobTitle": "Founder",
      "companyName": "Example Co",
      "schoolName": "Example University"
    },
    "sections": {
      "basic": {
        "items": [
          {
            "kind": "school",
            "title": "Graduated from Example University in 2018",
            "school": "Example University",
            "year": 2018
          },
          {
            "kind": "location",
            "title": "San Francisco, CA",
            "location": "San Francisco, CA"
          }
        ]
      },
      "personalLife": null,
      "jobs": null,
      "education": null,
      "passions": null,
      "worldview": null,
      "accomplishments": null,
      "controversies": null,
      "bestQualities": null,
      "netWorth": null,
      "portfolio": null,
      "families": null
    }
  }
}
The profile DTO is an allowlisted public shape. It does not expose raw contact details, phone numbers, internal moderation metadata, or profile-owner-only fields. Profiles may also include optional contribution sections such as mediaCredits, musicCredits, researchPapers, githubRepos, and books when public contribution data is available. Each profile read costs 1 credit by default; failed or not-found reads are refunded automatically.

​
Next steps