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

# Get a profile

> Fetch the public profile DTO for a single Orbit user by ID. Use profile IDs returned from search results to retrieve structured profile data.

The profile read endpoint returns a stable, public profile object for a given Orbit user. You get the profile ID from the `id` field in search results, then call this endpoint to retrieve structured data including display name, location, headline, and profile sections. Each successful read costs 1 credit. Reads that return a not-found response or fail for other reasons are automatically refunded.

Requests authenticate with a developer API key that has the `profile:read` scope. See [Authentication](/authentication).

<RequestExample>
  ```bash curl theme={"dark"}
  curl "https://api.orbitsearch.com/v2/developer/profiles/usr_a1b2c3d4e5f6" \
    -H "Authorization: Bearer sk_orb_REDACTED"
  ```

  ```javascript JavaScript theme={"dark"}
  const response = await fetch(
    "https://api.orbitsearch.com/v2/developer/profiles/usr_a1b2c3d4e5f6",
    {
      headers: {
        "Authorization": "Bearer sk_orb_REDACTED",
      },
    }
  );

  const profile = await response.json();
  console.log(profile.payload.displayName);
  ```

  ```python Python theme={"dark"}
  import requests

  response = requests.get(
      "https://api.orbitsearch.com/v2/developer/profiles/usr_a1b2c3d4e5f6",
      headers={"Authorization": "Bearer sk_orb_REDACTED"},
  )

  profile = response.json()
  print(profile["payload"]["displayName"])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 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,
        "images": {
          "items": [
            {
              "id": "image-1",
              "imageUrl": "https://...",
              "role": "primary",
              "type": "default",
              "question": "profile photo",
              "sources": []
            },
            {
              "id": "image-2",
              "imageUrl": "https://...",
              "role": "social_media",
              "sources": []
            }
          ]
        },
        "jobs": null,
        "education": null,
        "passions": null,
        "worldview": null,
        "accomplishments": null,
        "controversies": null,
        "bestQualities": null,
        "netWorth": null,
        "portfolio": null,
        "families": null,
        "mediaCredits": {
          "items": [
            {
              "kind": "media_credit",
              "title": "Example Documentary",
              "mediaType": "movie",
              "releaseDate": "2025-03-01",
              "roleType": "cast",
              "roleName": "Self"
            }
          ]
        },
        "musicCredits": {
          "items": [
            {
              "kind": "music_credit",
              "title": "Example Album",
              "releaseType": "Album",
              "firstReleaseDate": "2024-08-23",
              "creditName": "Example Artist",
              "role": "artist",
              "relationship": "artist"
            }
          ]
        }
      }
    }
  }
  ```
</ResponseExample>

## Path parameters

<ParamField path="id" type="string" required>
  The profile ID to fetch. This is the `id` value returned in the `payload.users` array from a [Search](/api/search/smart-search) response.
</ParamField>

## Response

<ResponseField name="status" type="string" required>
  Always `"success"` for a 200 response.
</ResponseField>

<ResponseField name="payload" type="object" required>
  <Expandable title="properties" defaultOpen>
    <ResponseField name="payload.id" type="string" required>
      The canonical public profile ID returned by the read. If the requested ID resolves through an alias, this can differ from the original requested ID.
    </ResponseField>

    <ResponseField name="payload.displayName" type="string">
      The user's public display name.
    </ResponseField>

    <ResponseField name="payload.personName" type="string">
      The person's public name when available. This usually matches `displayName`.
    </ResponseField>

    <ResponseField name="payload.aliases" type="string[]">
      Alternate public names, such as nicknames, maiden names, or stage names. Usernames and handles are not included. Omitted if no alternate names are available.
    </ResponseField>

    <ResponseField name="payload.avatarUrl" type="string">
      URL of the user's public avatar image. May be `null` if the user has not set a profile photo.
    </ResponseField>

    <ResponseField name="payload.profileUrl" type="string">
      The canonical public URL of the user's Orbit profile page.
    </ResponseField>

    <ResponseField name="payload.verified" type="boolean">
      Whether the profile has been verified by Orbit.
    </ResponseField>

    <ResponseField name="payload.location" type="object">
      The user's public location information.

      <Expandable title="properties">
        <ResponseField name="payload.location.city" type="string">
          City, region, and country string as entered by the user. Example: `"San Francisco, CA, US"`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="payload.headline" type="object">
      The user's professional headline, drawn from their current role or education.

      <Expandable title="properties">
        <ResponseField name="payload.headline.jobTitle" type="string">
          The user's current job title. May be `null`.
        </ResponseField>

        <ResponseField name="payload.headline.companyName" type="string">
          The user's current employer. May be `null`.
        </ResponseField>

        <ResponseField name="payload.headline.schoolName" type="string">
          The user's most recent school, shown when no job title is present. May be `null`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="payload.sections" type="object">
      Structured profile sections. Standard profile sections are returned as objects with section-specific `items` or as `null` when no public data is available. Contribution sections are optional and are only included when Orbit has public contribution data.

      <Expandable title="properties">
        <ResponseField name="payload.sections.basic" type="object | null">
          Basic profile information including school and location as entered by the user.
        </ResponseField>

        <ResponseField name="payload.sections.personalLife" type="object | null">
          Personal life information shared by the user.
        </ResponseField>

        <ResponseField name="payload.sections.images" type="object | null">
          Person-qualified profile images. Images are filtered through Orbit's slideshow image selector and include metadata such as `role`, `type`, `question`, and `sources` when available.
        </ResponseField>

        <ResponseField name="payload.sections.jobs" type="object | null">
          Work history shared by the user.
        </ResponseField>

        <ResponseField name="payload.sections.education" type="object | null">
          Education history shared by the user.
        </ResponseField>

        <ResponseField name="payload.sections.passions" type="object | null">
          Interests and passions shared by the user.
        </ResponseField>

        <ResponseField name="payload.sections.worldview" type="object | null">
          Worldview or values shared by the user.
        </ResponseField>

        <ResponseField name="payload.sections.accomplishments" type="object | null">
          Notable accomplishments shared by the user.
        </ResponseField>

        <ResponseField name="payload.sections.controversies" type="object | null">
          Public controversies associated with the user.
        </ResponseField>

        <ResponseField name="payload.sections.bestQualities" type="object | null">
          Best qualities highlighted by the user.
        </ResponseField>

        <ResponseField name="payload.sections.netWorth" type="object | null">
          Net worth information where publicly available.
        </ResponseField>

        <ResponseField name="payload.sections.portfolio" type="object | null">
          Portfolio or work samples shared by the user.
        </ResponseField>

        <ResponseField name="payload.sections.families" type="object | null">
          Family information shared by the user.
        </ResponseField>

        <ResponseField name="payload.sections.researchPapers" type="object">
          Public research paper contributions. Included only when Orbit has contribution data.
        </ResponseField>

        <ResponseField name="payload.sections.githubRepos" type="object">
          Public GitHub repository contributions. Included only when Orbit has contribution data.
        </ResponseField>

        <ResponseField name="payload.sections.mediaCredits" type="object">
          Public film, television, or other media credits. Included only when Orbit has contribution data.
        </ResponseField>

        <ResponseField name="payload.sections.musicCredits" type="object">
          Public music release credits. Included only when Orbit has contribution data.
        </ResponseField>

        <ResponseField name="payload.sections.books" type="object">
          Public book or authored-work contributions. Included only when Orbit has contribution data.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  The profile DTO is an allowlisted public shape. It does not expose raw contact details, phone numbers, full enrichment records, internal moderation or admin metadata, raw profile-owner widgets, or profile-owner-only progress fields.
</Note>

## Profile ID canonicalization

Profile reads accept IDs returned from Search, Deep Search, and previous profile
reads. All of those IDs remain valid. If the requested ID is an alias for an
existing identity, Orbit resolves the alias and returns the canonical public
profile.

This means the ID in the request path and the identifiers in the response may
not be identical. You can safely read either the alias ID or the canonical ID.
Treat `payload.id` as the canonical public profile ID after every successful
read, and prefer it for new writes or normalized storage.

Alias resolution is transparent. The response does not include separate
`requestedId`, `aliasOrbitId`, or `canonicalOrbitId` fields.

## Credits

Each successful profile read costs **1 credit**. Reads that return `developer_profile_not_found` or fail for other reasons are automatically refunded — you are only charged for profiles that are successfully returned.

## Rate limits

**50 requests per second** per API key, with bursts up to **250 requests**. Rate limits are tracked per key, not per IP address. A `429` response does not consume credits.

## Error responses

| Status | Code                                 | Description                                                                      |
| ------ | ------------------------------------ | -------------------------------------------------------------------------------- |
| `401`  | `missing_api_key`                    | No `Authorization: Bearer sk_orb_...` header was provided                        |
| `402`  | `developer_api_credits_insufficient` | Your remaining credits are lower than the cost of a profile read                 |
| `403`  | `invalid_api_key`                    | The key is malformed, revoked, expired, or unknown                               |
| `403`  | `missing_api_key_scope`              | The key does not have the `profile:read` scope                                   |
| `404`  | `developer_profile_not_found`        | The profile ID does not resolve to a public Orbit profile. The read is refunded. |
| `429`  | `developer_api_key_rate_limited`     | You have exceeded the Profile Read rate limit for this API key                   |

## Search-to-read flow

The example below shows the full flow: run a search, extract the first profile ID from the response, then fetch the full profile.

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

  ```javascript JavaScript theme={"dark"}
  // Step 1: run a search
  const searchResponse = await fetch(
    "https://api.orbitsearch.com/v2/developer/search",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer sk_orb_REDACTED",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ query: "founders in sf", numUsers: 10 }),
    }
  );

  const searchData = await searchResponse.json();
  const profileId = searchData.payload.users[0].id;

  // Step 2: fetch the full profile
  const profileResponse = await fetch(
    `https://api.orbitsearch.com/v2/developer/profiles/${profileId}`,
    {
      headers: {
        "Authorization": "Bearer sk_orb_REDACTED",
      },
    }
  );

  const profile = await profileResponse.json();
  console.log(profile.payload.displayName);
  ```

  ```python Python theme={"dark"}
  import requests

  # Step 1: run a search
  search_response = requests.post(
      "https://api.orbitsearch.com/v2/developer/search",
      headers={
          "Authorization": "Bearer sk_orb_REDACTED",
          "Content-Type": "application/json",
      },
      json={"query": "founders in sf", "numUsers": 10},
  )

  search_data = search_response.json()
  profile_id = search_data["payload"]["users"][0]["id"]

  # Step 2: fetch the full profile
  profile_response = requests.get(
      f"https://api.orbitsearch.com/v2/developer/profiles/{profile_id}",
      headers={"Authorization": "Bearer sk_orb_REDACTED"},
  )

  profile = profile_response.json()
  print(profile["payload"]["displayName"])
  ```
</CodeGroup>