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

# Network Graph

> Find how one person reaches another through Orbit's Network Graph, by the fewest people or by the strongest ties.

The Network Graph holds the ties between the people in Orbit. This endpoint returns the chain of people that connects one person to another, with the strength of each link and what ties each pair.

Two people are linked when Orbit holds a direct relationship between them (family, a stated connection, a mutual follow on social media) or when they worked, or studied, at the same place in the same years. A path has at most six links.

## Modes

| Mode | Returns |
| - | - |
| `shortest` (default) | The path with the fewest people. Among paths of that length, the strongest. |
| `strongest` | The path with the strongest ties. It can be one link longer than the shortest path. |

## Strength

Each link has a `strength` from 0 to 1. Family and long overlaps at one employer are strong. A mutual follow alone, or a short overlap, is weak. The path's `strength` is the strengths of its links multiplied, so a shorter path of strong ties scores higher than a longer path of weak ones.

## Credits

A found path is charged at the Network Graph path rate in the [pricing catalog](https://docs.orbitsearch.com/concepts/credits.md#credit-rates). A search that finds no path is free: `found` is `false`, `reason` says why, and `billing` is `null`. Send an `Idempotency-Key` header to retry a request without a second charge. See [Credits](https://docs.orbitsearch.com/concepts/credits.md#network-graph).

```bash curl theme={"dark"}
curl "https://api.orbitsearch.com/v3/people/FROM_PROFILE_ID/network/path?to=TO_PROFILE_ID&mode=strongest" \
  -H "Authorization: Bearer sk_orb_REDACTED"
```

```json 200 (found) theme={"dark"}
{
  "from_profile_id": "FROM_PROFILE_ID",
  "to_profile_id": "TO_PROFILE_ID",
  "mode": "strongest",
  "found": true,
  "degrees": 2,
  "strength": 0.275,
  "people": [
    { "profile_id": "FROM_PROFILE_ID", "name": "Ana Ruiz" },
    { "profile_id": "MIDDLE_PROFILE_ID", "name": "Ben Cole" },
    { "profile_id": "TO_PROFILE_ID", "name": "Cara Diaz" }
  ],
  "links": [
    {
      "from_profile_id": "FROM_PROFILE_ID",
      "to_profile_id": "MIDDLE_PROFILE_ID",
      "strength": 0.55,
      "relationships": ["coworker"],
      "organizations": [{ "name": "Acme", "overlap_years": 3 }],
      "schools": []
    },
    {
      "from_profile_id": "MIDDLE_PROFILE_ID",
      "to_profile_id": "TO_PROFILE_ID",
      "strength": 0.5,
      "relationships": ["colleague"],
      "organizations": [],
      "schools": []
    }
  ],
  "reason": null,
  "billing": {
    "id": "BILLING_OPERATION_ID",
    "pricingVersion": "2026-11-03",
    "reservedCredits": 5,
    "consumedCredits": 5,
    "releasedCredits": 0,
    "heldCredits": 0,
    "status": "settled"
  },
  "contract_version": "network-path.v1"
}
```

```json 200 (not found, free) theme={"dark"}
{
  "from_profile_id": "FROM_PROFILE_ID",
  "to_profile_id": "TO_PROFILE_ID",
  "mode": "shortest",
  "found": false,
  "degrees": null,
  "strength": null,
  "people": [],
  "links": [],
  "reason": "no_path",
  "billing": null,
  "contract_version": "network-path.v1"
}
```


## OpenAPI

````yaml openapi.json GET /v3/people/{profile_id}/network/path
openapi: 3.1.0
info:
  title: Orbit API
  version: 3.0.0
  description: Search for people and enrich known Orbit profiles.
servers:
  - url: https://api.orbitsearch.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Search
    description: Find people and poll search results.
  - name: Enrich
    description: Read or enrich known Orbit profiles.
  - name: People
    description: How people are connected.
  - name: Watchers
    description: Watch a profile on a schedule and read what each run found.
  - name: Webhooks
    description: Register endpoints that receive signed event deliveries.
  - name: Agents
    description: >-
      Let an AI agent create its own Orbit workspace, and hand it to the person
      it works for.
paths:
  /v3/people/{profile_id}/network/path:
    get:
      tags:
        - People
      summary: Find a Path in the Network Graph
      description: >-
        Find how one person reaches another through Orbit's Network Graph.
        `shortest` returns the path with the fewest people, and the strongest of
        those. `strongest` returns the path with the strongest ties, at most one
        link longer than the shortest. A path has at most six links. A found
        path is charged at the Network Graph path rate in the pricing catalog. A
        search that finds no path is free. Requires the `profile:read` scope.
      operationId: findNetworkPath
      parameters:
        - name: profile_id
          in: path
          required: true
          description: The Orbit profile ID (UUID) of the person the path starts from.
          schema:
            type: string
            format: uuid
        - name: to
          in: query
          required: true
          description: The Orbit profile ID (UUID) of the person the path ends at.
          schema:
            type: string
            format: uuid
        - name: mode
          in: query
          required: false
          description: '`shortest` (the fewest people) or `strongest` (the strongest ties).'
          schema:
            type: string
            enum:
              - shortest
              - strongest
            default: shortest
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: The path, or why no path was returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkPathResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          description: >-
            Network Graph paths are not available right now
            (`network_path_unavailable`). Nothing is charged. Retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        A client-generated key for a safe retry. If the body omits `request_id`,
        Orbit can use this value as the request ID.
      schema:
        type: string
        maxLength: 200
  schemas:
    NetworkPathResponse:
      type: object
      required:
        - from_profile_id
        - to_profile_id
        - mode
        - found
        - degrees
        - strength
        - people
        - links
        - reason
        - billing
        - contract_version
      properties:
        from_profile_id:
          type: string
          format: uuid
          description: The person the path starts from.
        to_profile_id:
          type: string
          format: uuid
          description: The person the path ends at.
        mode:
          type: string
          enum:
            - shortest
            - strongest
          description: The mode of the search.
        found:
          type: boolean
          description: True when Orbit found a path.
        degrees:
          type:
            - integer
            - 'null'
          minimum: 1
          description: >-
            The number of links between the two people. 1 means they are tied
            directly. Null when no path was found.
        strength:
          type:
            - number
            - 'null'
          minimum: 0
          maximum: 1
          description: >-
            The strength of the whole path: the strengths of its links
            multiplied. Null when no path was found.
        people:
          type: array
          items:
            type: object
            required:
              - profile_id
              - name
            properties:
              profile_id:
                type:
                  - string
                  - 'null'
              name:
                type:
                  - string
                  - 'null'
          description: >-
            The people on the path, in order, from `from_profile_id` to
            `to_profile_id`. Empty when no path was found.
        links:
          type: array
          items:
            $ref: '#/components/schemas/NetworkPathLink'
          description: The links between consecutive people. Empty when no path was found.
        reason:
          type:
            - string
            - 'null'
          enum:
            - no_path
            - search_limit
            - not_in_graph
            - null
          description: >-
            Why no path was returned: `no_path` (none within six links),
            `search_limit` (the search reached its limit first) or
            `not_in_graph` (a person is not in Orbit's people graph yet). Null
            when a path was found.
        billing:
          oneOf:
            - $ref: '#/components/schemas/OperationBilling'
            - type: 'null'
          description: >-
            The charge for a found path. Null when no path was found: those
            searches are free.
        contract_version:
          type: string
          enum:
            - network-path.v1
    ErrorResponse:
      type: object
      required:
        - status
        - error
      properties:
        status:
          type: string
          enum:
            - failed
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            requiredCredits:
              type: integer
              minimum: 0
              description: >-
                Credits required when the error is
                developer_api_credits_insufficient.
            remainingCredits:
              type: integer
              minimum: 0
              description: >-
                Available credits when the error is
                developer_api_credits_insufficient.
    NetworkPathLink:
      type: object
      required:
        - from_profile_id
        - to_profile_id
        - strength
        - relationships
        - organizations
        - schools
      properties:
        from_profile_id:
          type:
            - string
            - 'null'
          description: The profile ID of the person on the near side of this link.
        to_profile_id:
          type:
            - string
            - 'null'
          description: The profile ID of the person on the far side of this link.
        strength:
          type: number
          minimum: 0
          maximum: 1
          description: How strong this tie is, from 0 to 1.
        relationships:
          type: array
          items:
            type: string
          description: >-
            What ties the two people, for example `coworker`, `classmate`,
            `mutual`, `sibling` or `colleague`.
        organizations:
          type: array
          items:
            $ref: '#/components/schemas/NetworkPathPlace'
          description: >-
            Employers where both people worked in the same years, longest
            overlap first.
        schools:
          type: array
          items:
            $ref: '#/components/schemas/NetworkPathPlace'
          description: Schools where both people studied in the same years.
    OperationBilling:
      type: object
      description: >-
        Credits held and spent for the billing operation behind this request.
        Poll until status is settled to read the final consumedCredits.
      required:
        - id
        - pricingVersion
        - reservedCredits
        - consumedCredits
        - releasedCredits
        - heldCredits
        - status
      properties:
        id:
          type: string
          format: uuid
          description: The billing operation behind this request.
        pricingVersion:
          type: string
          description: The pricing catalog version this operation settles under.
        reservedCredits:
          type: integer
          minimum: 0
          description: The credits held for this operation.
        consumedCredits:
          type: integer
          minimum: 0
          description: The credits charged so far.
        releasedCredits:
          type: integer
          minimum: 0
          description: The credits returned to your balance.
        heldCredits:
          type: integer
          minimum: 0
          description: >-
            The credits still held: reservedCredits less consumedCredits and
            releasedCredits.
        status:
          type: string
          enum:
            - open
            - settled
          description: >-
            open while the operation can still charge, and settled once its
            charge is final.
    NetworkPathPlace:
      type: object
      required:
        - name
        - overlap_years
      properties:
        name:
          type:
            - string
            - 'null'
          description: The employer or school.
        overlap_years:
          type: number
          minimum: 0
          description: The years the two people were both there.
  responses:
    BadRequest:
      description: The request is not valid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: The API key is missing or not valid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InsufficientCredits:
      description: >-
        The available API credit balance cannot cover the requested work. Top up
        before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: The API key does not have the required scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: The API key exceeded a rate limit.
      headers:
        Retry-After:
          description: Seconds to wait before another request.
          schema:
            type: integer
            minimum: 0
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Orbit API key
      description: Use an Orbit API key from the Developer Dashboard.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.