> For the complete documentation index, see [llms.txt](https://docs.biobox.io/guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.biobox.io/guide/how-to/ask-biobox-with-claude/tools/find-paths.md).

# find\_paths — Find shortest path

Find shortest path

Find shortest path

## What it does

Find the shortest path between two graph nodes (identified by uuid), returning a readable BxQL path summary plus the ordered list of nodes along the way AND the relationships (edges) linking them, with an aggressive cap on traversal depth.

**When to use:** the user asks "how are X and Y connected?" or "is there a path between them?"; you need to relate two known entities through the graph (e.g. a gene and a brain-disorder gene).

**When NOT to use:** you want one node's direct neighbors, not a path to another node (use get\_entity\_connections); you only have a name, not a uuid (use search\_entities to resolve each endpoint to a uuid first); you need a custom traversal pattern, not a plain shortest path (use run\_graph\_query).

**Parameters:**

* `start` — uuid of the path's start node (from a search\_entities or get\_entity hit). The elementId the traversal needs is resolved server-side — no elementId is ever taken or exposed.
* `end` — uuid of the path's end node (from a search\_entities or get\_entity hit).
* `maxHops` — max traversal depth (optional; default 4, hard-capped at 6 — larger values are clamped).

**Returns:** An object { summary, hops, nodes, edges, maxHopsApplied }. `summary` is the whole path as one directional BxQL pattern — the readable line, e.g. "(Gene:ERBB4)<-\[:interacts with]-(Gene:LRRC7)" (nodes render as (dbLabel:displayName); the arrow shows which way each relationship points, so no reversal reasoning is needed); `hops` is the edge count (nodes - 1, 0 when none); `nodes` is the ordered path (each: uuid, displayName, dbLabels); `edges` is the same relationships as directed triples (each: { from, label, to, properties }, where edges\[k] is the k-th segment between nodes\[k] and nodes\[k+1], from/to are the relationship's endpoint uuids in its true stored direction — chain them into get\_entity — and properties are the edge's stored attributes e.g. score/source-DB); `maxHopsApplied` is the depth the traversal actually ran under after the cap. A disconnected pair returns a null `summary` and empty `nodes`/`edges` with hops 0 — that is an explicit answer, not an error. An unknown start/end uuid returns a 404 Not Found error (isError) naming it.

## Parameters

| Parameter | Type   | Required | Description                                                                                                                                                                    |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `start`   | string | yes      | uuid of the path's start node (from a search\_entities or get\_entity hit). The elementId the traversal needs is resolved server-side — no elementId is ever taken or exposed. |
| `end`     | string | yes      | uuid of the path's end node (from a search\_entities or get\_entity hit).                                                                                                      |
| `maxHops` | number | no       | max traversal depth (optional; default 4, hard-capped at 6 — larger values are clamped).                                                                                       |

## Response

```ts
{
  summary: string | null;
  hops: number;
  nodes: Array<{
    uuid: string | null;
    displayName: string | null;
    dbLabels: string[];
  }>;
  edges: Array<{
    from: string | null;
    label: string | null;
    to: string | null;
    properties: { [key: string]: unknown } | null;
  }>;
  maxHopsApplied: number;
}
```

## Example

```json
// find_paths({"start":"ENSG00000178568","end":"ENSG00000033122"})
{
  "start": "ENSG00000178568",
  "end": "ENSG00000033122"
}
```

Response (arrays truncated):

```json
{
  "summary": "(Gene:ERBB4)<-[:interacts with]-(Gene:LRRC7)",
  "hops": 1,
  "nodes": [
    {
      "uuid": "ENSG00000178568",
      "displayName": "ERBB4",
      "dbLabels": [
        "Gene",
        "ProteinCoding"
      ]
    },
    {
      "uuid": "ENSG00000033122",
      "displayName": "LRRC7",
      "dbLabels": [
        "Gene",
        "ProteinCoding"
      ]
    }
  ],
  "edges": [
    {
      "from": "ENSG00000033122",
      "label": "interacts with",
      "to": "ENSG00000178568",
      "properties": {
        "mode": "reaction",
        "score": 165,
        "externalDbSource": "String DB",
        "externalDbVersion": "12.0"
      }
    }
  ],
  "maxHopsApplied": 4
}
```