Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.orbitsearch.com/llms.txt

Use this file to discover all available pages before exploring further.

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. The examples below use $API_BASE as a placeholder for the API base URL you received when signing up.

​
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 smart search endpoint. The query and numUsers fields are both required.
curl -X POST "$API_BASE/v2/social/profiles/searches/smart" \
  -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": [
      {
        "userId": "usr_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 a userId field. Use this to fetch a full profile in the next step.
4

Fetch a full profile

Pass the userId from any search result to GET /v2/developer/profiles/:id to retrieve the complete public profile DTO.
# Extract userId from the first search result and fetch its profile
SEARCH_RESPONSE=$(
  curl -s -X POST "$API_BASE/v2/social/profiles/searches/smart" \
    -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].userId')

curl "$API_BASE/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": "usr_a1b2c3d4e5f6",
    "orbitId": "orbit-profile-id",
    "displayName": "Ada Lovelace",
    "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": {
        "school": "Example University",
        "location": "San Francisco"
      },
      "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. Each profile read costs 1 credit by default; failed or not-found reads are refunded automatically.

​
Next steps