Skip to main content
This guide walks you through the three steps you need to make your first working Orbit Search request: getting an API key, running a search, and reading a profile. By the end you’ll have a bearer token, a search result, and a structured profile object — all from the API base URL https://api.orbitsearch.com.
1

Get an API key

Log in to the Orbit developer dashboard and generate a personal API key with the search:read and profile:read scopes.Copy the raw key when the dashboard shows it. It starts with sk_orb_ and is shown only once.
export ORBIT_API_KEY="sk_orb_REDACTED"
The public developer API does not create your first key. You need a dashboard-issued sk_orb_... key before making API requests. Store it in a secrets manager or environment variable before closing the dashboard modal.
2

Run a search

Use POST /v2/developer/search to search the Orbit index in plain English. Pass your API key as a bearer token. The query and numUsers fields are both required.
curl -X POST "https://api.orbitsearch.com/v2/developer/search" \
  -H "Authorization: Bearer sk_orb_REDACTED" \
  -H "Idempotency-Key: your-unique-request-id" \
  -H "Content-Type: application/json" \
  -d '{"query":"founders in sf","numUsers":10}'
A successful response looks like this:
{
  "status": "success",
  "searchId": "uuid",
  "payload": {
    "users": []
  }
}
Each object in payload.users includes an id you can use to fetch the full profile. The response also includes the X-Developer-API-Credits-Remaining header so you can track how many credits you have left.
Include an Idempotency-Key header on every search request. If your client retries after a network error, the same key prevents you from being charged twice for the same search. Use a fresh key for each logically distinct request.
Search costs 2 credits per successful request. If the search returns no results or fails, the reservation is refunded and no credits are consumed. Requests that exceed your credit balance return a 402 with code developer_api_credits_insufficient before any search work begins.
3

Read a profile

Take an id from your search results and pass it to GET /v2/developer/profiles/:id. Each profile read costs 1 credit; not-found and failed reads are refunded.
# Extract the first profile id from your search response, then fetch the profile
SEARCH_RESPONSE=$(
  curl -s -X POST "https://api.orbitsearch.com/v2/developer/search" \
    -H "Authorization: Bearer sk_orb_REDACTED" \
    -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 sk_orb_REDACTED"
The profile response contains a structured, public-safe 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 exposes a public-safe allowlist of fields. It does not include 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.