> ## 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.

# Run your first search and read a profile with Orbit

> Go from zero to receiving profile results with Orbit Search — get an API key, run a search, and fetch a full profile record in minutes.

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

<Steps>
  <Step title="Get an API key">
    Open the [Orbit developer dashboard](https://developer.orbitsearch.com/dashboard/keys) and generate a personal API key with the `search:read` and `profile:read` scopes. Copy the raw `sk_orb_...` key when it appears.

    ```bash theme={"dark"}
    export ORBIT_API_KEY="sk_orb_REDACTED"
    ```

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="Run a global search">
    Send a `POST` request to the developer search endpoint. The `query` and `numUsers` fields are both required.

    <CodeGroup>
      ```bash curl theme={"dark"}
      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}'
      ```

      ```javascript JavaScript theme={"dark"}
      const response = await fetch(
        `https://api.orbitsearch.com/v2/developer/search`,
        {
          method: "POST",
          headers: {
            Authorization: `Bearer ${ORBIT_API_KEY}`,
            "Idempotency-Key": crypto.randomUUID(),
            "Content-Type": "application/json",
          },
          body: JSON.stringify({ query: "founders in sf", numUsers: 10 }),
        }
      );
      const data = await response.json();
      ```
    </CodeGroup>

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="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.

    ```json theme={"dark"}
    {
      "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.
  </Step>

  <Step title="Fetch a full profile">
    Pass the `id` from any search result to `GET /v2/developer/profiles/:id` to retrieve the complete public profile DTO.

    <CodeGroup>
      ```bash curl theme={"dark"}
      # 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"
      ```

      ```javascript JavaScript theme={"dark"}
      const searchRes = await fetch(
        `https://api.orbitsearch.com/v2/developer/search`,
        {
          method: "POST",
          headers: {
            Authorization: `Bearer ${ORBIT_API_KEY}`,
            "Content-Type": "application/json",
          },
          body: JSON.stringify({ query: "founders in sf", numUsers: 10 }),
        }
      );
      const searchData = await searchRes.json();
      const profileId = searchData.payload.users[0]?.id;

      const profileRes = await fetch(
        `https://api.orbitsearch.com/v2/developer/profiles/${profileId}`,
        {
          headers: { Authorization: `Bearer ${ORBIT_API_KEY}` },
        }
      );
      const profile = await profileRes.json();
      ```
    </CodeGroup>

    A successful profile read returns a stable public profile DTO:

    ```json theme={"dark"}
    {
      "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.
  </Step>
</Steps>

## Next steps

* Scope your searches to a custom people corpus using [Search Directories](/guides/directory-setup).
* Learn how to safely rotate your API key in [Key Rotation](/guides/key-rotation).
* See every error code your application should handle in [Error Handling](/guides/error-handling).