> This page is for version v4 (default).
> For other versions, use one of these documentation indexes:
> - v4 (default): https://help.getzep.com/v4/llms.txt
> - v3: https://help.getzep.com/v3/llms.txt
> - v2: https://help.getzep.com/v2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://help.getzep.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.getzep.com/_mcp/server.

# List node neighbors

POST https://api.getzep.com/api/v4/graphs/{graph_uuid}/nodes/{node_uuid}/neighbors
Content-Type: application/json

Reference: https://help.getzep.com/sdk-reference/graph/node/list-neighbors

## Authentication

- `Authorization` header (required) (prefixed with ` Api-Key  `) — Type "Api-Key" followed by a space and the project API key.

## Request

### Path parameters

- `graph_uuid` (string, required) — The UUID of the graph. For a user graph, you can also use the UUID of the user.
- `node_uuid` (string, required) — Node UUID

### Query parameters

- `page_size` (integer, optional, default: 50) — The maximum number of items in one page. The SDK method returns a pager. In Python, `.items` holds only the first page. In TypeScript, `.data` holds only the first page. To read every page, iterate the pager: use `for` or `list(...)` in Python, or `for await` in TypeScript. In Go, the method returns one page, and `Iterator()` reads all pages.
- `cursor` (string, optional) — Opaque page cursor
- `order_by` (enum, optional) — Sort field
  - Allowed values: `uuid`, `created_at`
- `order` (enum, optional) — Sort direction: asc or desc
  - Allowed values: `asc`, `desc`

### Body (application/json)

This endpoint expects a v4.NeighborsRequest.

- `direction` (enum, optional) — The edge orientation to follow from the node: in, out, or both.
  - Allowed values: `in`, `out`, `both`
- `filters` (v4.SearchFilters, optional) — Filters constraining the connecting edges and the neighbor nodes.

## Response

### 200

OK

- `items` (list of v4.NeighborEntry, optional) — The neighboring nodes and their connecting edges on this page.
- `next_cursor` (string, optional) — The cursor to pass as the next request's cursor to fetch the following page; absent when no further pages remain.
- `total_size` (integer, optional) — Omitted for this collection; use next_cursor to detect the end of pagination.

## Errors

### 400 Bad Request Error

Bad Request

- `error` (v4.ErrorBody, optional)

### 401 Unauthorized Error

Unauthorized

- `error` (v4.ErrorBody, optional)

### 403 Forbidden Error

Forbidden

- `error` (v4.ErrorBody, optional)

### 404 Not Found Error

Not Found

- `error` (v4.ErrorBody, optional)

### 409 Conflict Error

Conflict

- `error` (v4.ErrorBody, optional)

## Types

### v4.SearchFilters

- `connected_node_uuids` (list of string, optional) — Include edges connected to any of these node UUIDs. Node search does not support this filter.
- `content_policy_violated` (boolean, optional) — Match episodes by their content-policy result. Supported only on episode search when the project setting include_policy_violating_episodes is true.
- `date_filters` (v4.DateFilters, optional) — Filter results by temporal values.
- `edge_types` (list of string, optional) — Include results with any of these edge types. Node search does not support this filter.
- `edge_uuids` (list of string, optional) — Include results with any of these edge UUIDs. Node search does not support this filter.
- `episode_uuids` (list of string, optional) — Include results derived from any of these episode UUIDs.
- `exclude_edge_types` (list of string, optional) — Exclude results with any of these edge types. Node search does not support this filter.
- `exclude_node_labels` (list of string, optional) — Exclude nodes that have any of these labels. On an edge list, the API excludes an edge when its source node or its target node has one of these labels. Edge search does not support this filter.
- `metadata_filters` (v4.MetadataFilterGroup, optional) — Filter results by episode metadata.
- `node_labels` (list of string, optional) — Include only nodes that have at least one of these labels. On an edge list, the source node and the target node of each edge must each have at least one of these labels. Edge search does not support this filter.
- `property_filters` (list of v4.PropertyFilter, optional) — Filter results by node or edge properties.
- `source_node_uuids` (list of string, optional) — Include edges that start at any of these node UUIDs. Node search does not support this filter.
- `target_node_uuids` (list of string, optional) — Include edges that end at any of these node UUIDs. Node search does not support this filter.

### v4.NeighborEntry

- `edges` (list of v4.Edge, optional) — The edges connecting the neighboring node to the queried node.
- `node` (v4.Node, optional) — The neighboring node reached from the queried node.

### v4.ErrorBody

- `code` (string, optional)
- `details` (map from string to any, optional)
- `message` (string, optional)
- `param` (string, optional)
- `request_id` (string, optional)

### v4.DateFilters

- `any_of` (list of v4.DateFilterGroup, optional) — Each group is combined with OR logic.

### v4.MetadataFilterGroup

- `filters` (list of v4.MetadataFilter, optional) — The metadata predicates in this group.
- `groups` (list of v4.MetadataFilterGroup, optional) — The nested metadata groups in this group.
- `type` (enum, optional) — The logical operator for this group.
  - Allowed values: `and`, `or`

### v4.PropertyFilter

- `operator` (enum, optional) — The lowercase comparison operator.
  - Allowed values: `eq`, `ne`, `gt`, `lt`, `gte`, `lte`, `in`, `is_null`, `is_not_null`
- `property_name` (string, optional) — The property name to compare.
- `value` (V4PropertyFilterValue, optional) — The comparison value. Use an array for in. Its string members must be non-empty, contain no comma, and have no surrounding whitespace.

### v4.Edge

- `attributes` (map from string to any, optional) — Additional attributes of the edge.
- `created_at` (string, optional) — The time the edge was created.
- `episode_uuids` (list of string, optional) — The episodes this edge was derived from.
- `expired_at` (string, optional) — The time the fact was superseded or removed.
- `fact` (string, optional) — The natural-language fact this edge represents.
- `graph_uuid` (string, optional) — The unique identifier of the graph this edge belongs to.
- `hyperedge_uuid` (string, optional) — The unique identifier of the hyperedge this edge is a member of. Omitted when the edge is not part of a hyperedge.
- `invalid_at` (string, optional) — The time at which the fact stopped being true.
- `name` (string, optional) — The name of the edge, in upper snake case, for example RELATES_TO.
- `relevance` (double, optional) — A cross-encoder-derived relevance score, present only when the cross-encoder reranker scored this result; like score, it is omitted from plain list results.
- `scope` (string, optional) — The kind of edge this is, for example entity or episodic.
- `score` (double, optional) — The ranking score returned with every search result; omitted when the edge appears in a plain list rather than a search result.
- `source_node_labels` (list of string, optional) — The current labels of the source node. This is read at request time rather than stored on the edge, and is omitted when the source node cannot be resolved.
- `source_node_name` (string, optional) — The current name of the source node. This is read at request time rather than stored on the edge, and is omitted when the source node cannot be resolved.
- `source_node_uuid` (string, optional) — The unique identifier of the edge's source node.
- `target_node_labels` (list of string, optional) — The current labels of the target node. This is read at request time rather than stored on the edge, and is omitted when the target node cannot be resolved.
- `target_node_name` (string, optional) — The current name of the target node. This is read at request time rather than stored on the edge, and is omitted when the target node cannot be resolved.
- `target_node_uuid` (string, optional) — The unique identifier of the edge's target node.
- `user_uuid` (string, optional) — The unique identifier of the user that owns the graph. Present only when the graph is a user graph.
- `uuid` (string, optional) — The unique identifier of the edge.
- `valid_at` (string, optional) — The time from which the fact is considered true.

### v4.Node

- `episode_uuids` (list of string, required) — The UUIDs of the live episodes that mention this node, newest first. The list is complete when `episode_uuids_truncated` is false. The list holds the newest 100 when the node has more than 100 source episodes; list episodes with the `mentioned_node_uuids` filter to read them all.
- `episode_uuids_truncated` (boolean, required) — True when the node has more than 100 source episodes, so `episode_uuids` holds only the newest 100, or when provenance is unavailable. False means `episode_uuids` is the complete set.
- `attributes` (map from string to any, optional) — Additional attributes of the node, as defined by its entity type.
- `created_at` (string, optional) — The time the node was created.
- `degree` (integer, optional) — The count of live entity edges that touch this node, in both directions. Present only when the list request orders by `degree`.
- `graph_uuid` (string, optional) — The unique identifier of the graph this node belongs to.
- `labels` (list of string, optional) — The entity type labels assigned to the node.
- `name` (string, optional) — The name of the entity that the node represents.
- `relevance` (double, optional) — A cross-encoder-derived relevance score, present only when the cross-encoder reranker scored this result; like score, it is omitted from plain list results.
- `score` (double, optional) — The ranking score returned with every search result; omitted when the node appears in a plain list rather than a search result.
- `summary` (string, optional) — A generated summary of the entity that the node represents.
- `user_uuid` (string, optional) — The unique identifier of the user that owns the graph. Present only when the graph is a user graph.
- `uuid` (string, optional) — The node UUID, assigned by Zep.

### v4.DateFilterGroup

- `all_of` (list of v4.DateFilter, optional) — All conditions in the group must match.

### v4.MetadataFilter

- `operator` (enum, optional) — The lowercase comparison operator.
  - Allowed values: `eq`, `ne`, `gt`, `lt`, `gte`, `lte`, `in`, `contains`, `is_null`, `is_not_null`
- `property_name` (string, optional) — The metadata property name to compare.
- `value` (V4MetadataFilterValue, optional) — The comparison value. Use an array for in, a non-empty string for contains, and omit the field for null operators.

### V4PropertyFilterValue

The comparison value. Use an array for in. Its string members must be non-empty, contain no comma, and have no surrounding whitespace.

### v4.DateFilter

- `field` (enum, optional) — The temporal field to compare.
  - Allowed values: `created_at`, `valid_at`, `invalid_at`, `expired_at`
- `operator` (enum, optional) — The lowercase comparison operator.
  - Allowed values: `eq`, `ne`, `gt`, `lt`, `gte`, `lte`, `is_null`, `is_not_null`
- `value` (string, optional) — The RFC 3339 timestamp. Omit this field for null operators.

### V4MetadataFilterValue

The comparison value. Use an array for in, a non-empty string for contains, and omit the field for null operators.

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "items": [
    {
      "edges": [
        {
          "attributes": {},
          "created_at": "string",
          "episode_uuids": [
            "string"
          ],
          "expired_at": "string",
          "fact": "string",
          "graph_uuid": "string",
          "hyperedge_uuid": "string",
          "invalid_at": "string",
          "name": "string",
          "relevance": 1.1,
          "scope": "string",
          "score": 1.1,
          "source_node_labels": [
            "string"
          ],
          "source_node_name": "string",
          "source_node_uuid": "string",
          "target_node_labels": [
            "string"
          ],
          "target_node_name": "string",
          "target_node_uuid": "string",
          "user_uuid": "string",
          "uuid": "string",
          "valid_at": "string"
        }
      ],
      "node": {
        "episode_uuids": [
          "string"
        ],
        "episode_uuids_truncated": true,
        "attributes": {},
        "created_at": "string",
        "degree": 1,
        "graph_uuid": "string",
        "labels": [
          "string"
        ],
        "name": "string",
        "relevance": 1.1,
        "score": 1.1,
        "summary": "string",
        "user_uuid": "string",
        "uuid": "string"
      }
    }
  ],
  "next_cursor": "string",
  "total_size": 1
}
```