> 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 nodes

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

Lists the nodes of a graph and returns one page of results. The default `page_size` is 50, and the maximum `page_size` is 100.
You can sort by `uuid`, `created_at`, or `degree`. The default sort is `uuid` in descending order.
You cannot use these `filters` fields: `connected_node_uuids`, `source_node_uuids`, `target_node_uuids`, and `content_policy_violated`.
If the request has an unsupported or unknown filter field, the API returns an `unsupported_filter` error.

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

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

### 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 key: uuid (default), created_at, or degree
  - Allowed values: `uuid`, `created_at`, `degree`
- `order` (enum, optional) — Sort direction: asc or desc (default desc)
  - Allowed values: `asc`, `desc`

### Body (application/json)

This endpoint expects a v4.NodeListRequest.

- `filters` (v4.NodeListFilters, optional) — Filters that limit the items in the list. The operation description names the filter fields that the operation does not support.

## Response

### 200

OK

- `items` (list of v4.Node, optional) — The nodes 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.NodeListFilters

- `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.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.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.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": [
    {
      "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
}
```