> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Session Graph Neighbors

Fetch the neighbors of a set of vertices in a graph session object.

## **POST** `/revisions/:id/data/query` (Command: `list_session_graph_neighbors`)

Returns the edges incident to the given source vertices and the vertices on the far end of those
edges. The response is paginated and can be filtered by edge direction and type.

### Request Body

| Parameter        | Type            | Required | Description                                                         |
| :--------------- | :-------------- | :------- | :------------------------------------------------------------------ |
| `engine`         | string          | Yes      | Must be `workflow_blobhub`.                                         |
| `command`        | string          | Yes      | Must be `list_session_graph_neighbors`.                             |
| `session_id`     | string          | Yes      | The ID of the session that owns the graph envelope.                 |
| `alias`          | string          | Yes      | Alias of the graph session object.                                  |
| `from`           | array of string | Yes      | Source vertex ids whose neighbors to fetch.                         |
| `direction`      | string          | No       | Edge traversal direction: `"out"`, `"in"`, or `"both"` (default).   |
| `label`          | string          | No       | Filter edges by `label`. Omit to return all edge types.             |
| `neighbor_label` | string          | No       | Filter neighbor vertices by label.                                  |
| `cursor`         | string          | No       | Opaque pagination cursor returned by a previous call.               |
| `limit`          | integer         | No       | Maximum number of edges to return. Server enforces its own maximum. |

**`direction`** — controls which edges are traversed (default: `"both"`):

* `"out"` — edges where `from_id` is in `from` (outgoing).
* `"in"` — edges where `to_id` is in `from` (incoming).
* `"both"` — both directions. When paginating with `direction: "both"`, the cursor is a composite
  token that tracks progress through both sets independently; always pass back the cursor verbatim.

**`label`** and **`neighbor_label`** may be combined to narrow results further (e.g. only
`"depends_on"` edges leading to vertices labelled `"task"`).

### Response

| Parameter  | Type            | Description                                                       |
| :--------- | :-------------- | :---------------------------------------------------------------- |
| `edges`    | array of object | The matching edges, in insertion order.                           |
| `vertices` | array of object | The neighbor vertices referenced by the returned edges (deduped). |
| `cursor`   | string or null  | Pagination cursor; `null` when this is the last page.             |

### Errors

* `invalid_graph_envelope` — the alias does not exist or its `value.type` is not `"graph"`.
* `invalid_cursor` — the cursor is malformed or has expired.

### Example

<CodeGroup>
  ```json Request theme={null}
  {
    "engine": "workflow_blobhub",
    "command": "list_session_graph_neighbors",
    "session_id": "sess_001",
    "alias": "task_graph",
    "from": ["task:2"],
    "direction": "out",
    "label": "depends_on"
  }
  ```

  ```json Response theme={null}
  {
    "edges": [
      {
        "element_id": "e:1",
        "type": "edge",
        "label": "depends_on",
        "from_id": "task:2",
        "to_id": "task:1",
        "props": {},
        "rev": 1,
        "created_at": "2026-06-06T10:00:00.000000+00:00",
        "updated_at": "2026-06-06T10:00:00.000000+00:00",
        "user_id": "usr_001"
      }
    ],
    "vertices": [
      {
        "element_id": "task:1",
        "type": "vertex",
        "labels": ["task"],
        "props": { "title": "Research", "status": "in_progress" },
        "rev": 2,
        "created_at": "2026-06-06T10:00:00.000000+00:00",
        "updated_at": "2026-06-06T10:00:01.000000+00:00",
        "user_id": "usr_001"
      }
    ],
    "cursor": null
  }
  ```
</CodeGroup>

### See also

* [Graph session object](/blob-types/workflow/session-objects/graph/introduction) — envelope shape and element schema.
* [Apply Session Graph Mutations](/blob-types/workflow/operations/apply-session-graph-mutations) — write vertices and edges.
* [Query Session Graph](/blob-types/workflow/operations/query-session-graph) — multi-hop traversal with a query AST.
* [List Session Graph Elements](/blob-types/workflow/operations/list-session-graph-elements) — paginate all elements.
* [Get Session Graph Element](/blob-types/workflow/operations/get-session-graph-element) — fetch a single element by id.
* [Get Session Graph Elements](/blob-types/workflow/operations/get-session-graph-elements) — fetch multiple elements by id.