Reading Data from the Graph

Zep provides APIs to read Edges, Nodes, and Episodes from the graph. You can read one item by its uuid, or list the items of one type in one graph. Each call takes the graph_uuid of the graph. For a user graph, use the graph_uuid that the user create response gave you. For a shared Context Graph, use the uuid that the graph create response gave you.

The dashboard graph visualizer includes a graph visualizer assistant that answers questions about the graph you are viewing.

Examples of each retrieval method are provided below.

Reading Edges

Alongside source_node_uuid and target_node_uuid, edge responses can include source_node_name, target_node_name, source_node_labels, and target_node_labels. These are projections of current node state, so a node rename shows up on the next read. Zep omits the corresponding fields when an endpoint node cannot be resolved, and omits all four when the API key has active attribute constraints. The edge is still returned with its endpoint UUIDs.

from zep_cloud.client import Zep
client = Zep(
    api_key=API_KEY,
)
edge = client.graph.edge.get(graph_uuid, edge_uuid)

Reading nodes

from zep_cloud.client import Zep
client = Zep(
    api_key=API_KEY,
)
node = client.graph.node.get(graph_uuid, node_uuid)

Reading Episodes

from zep_cloud.client import Zep
client = Zep(
    api_key=API_KEY,
)
episode = client.graph.episode.get(graph_uuid, episode_uuid)

Listing artifacts in bulk

The methods above return a single artifact by its uuid. To enumerate artifacts of a given type in bulk, use the list methods. Where searching the graph ranks results by relevance to a query, the list methods return everything of a given type in a graph, with filtering, sorting, and pagination applied server-side.

Reach for these methods when you are not answering a question but enumerating data: rendering an entity browser or a facts table in a UI, exporting a graph, or auditing what a graph contains. Cursor pagination lets you walk large graphs in stable, predictable pages instead of pulling everything into memory at once.

Each artifact type has one list method. The method takes the graph_uuid and works the same way on a user graph and on a shared Context Graph:

Shared parameters

graph.node.list also takes order_by ("uuid" or "degree") and order ("asc" or "desc"). The default is uuid, descending.

List filters

The filters object is a free-form object in all three SDKs: Dict[str, Any] in Python, Record<string, unknown> in TypeScript, and map[string]any in Go. Write the keys in snake case. The server checks each key, and combines each key with the scope of the list with a logical AND. A key that the list cannot apply gets HTTP 400 with the code unsupported_filter.

The keys use the same semantics as the Search Filters of graph search: date_filters (any_of groups of all_of leaf predicates on created_at, valid_at, invalid_at, or expired_at), edge_types / exclude_edge_types, node_labels / exclude_node_labels, property_filters, and metadata_filters. These keys apply to some lists only:

• connected_node_uuids, source_node_uuids, and target_node_uuids apply to graph.edge.list only.
• episode_uuids selects the nodes or edges that the listed episodes mention. The observation, thread summary, and document summary lists do not accept it.
• graph.episode.list accepts only mentioned_node_uuids and the metadata filter.

Listing nodes

List the entities in a graph.

from zep_cloud.client import Zep
client = Zep(api_key=API_KEY)
# 20 entities per page. The pager fetches the next page when you iterate past the current page.
for node in client.graph.node.list(graph_uuid, limit=20):
    print(node.name, node.created_at)

See Entities for per-type detail.

To rank nodes by how connected they are, pass order_by="degree" on graph.node.list. Each returned node then carries a degree field: the count of live entity edges that touch it. The count spans the whole graph and does not change when filters narrows which nodes come back. A node has the degree field only when the request orders by degree.

# The most-connected entities in a graph.
for node in client.graph.node.list(graph_uuid, order_by="degree", order="desc", limit=20):
    print(node.name, node.degree)

Listing edges with filters

Pass a filters object to narrow the results. The example below lists facts on a graph that were created in July 2025 and use specific edge types.

from zep_cloud.client import Zep
client = Zep(api_key=API_KEY)
edges = client.graph.edge.list(
    graph_uuid,
    filters={
        "edge_types": ["WORKS_WITH", "COLLABORATES_ON"],
        "date_filters": {
            "any_of": [
                {
                    "all_of": [
                        {"field": "created_at", "operator": "gte", "value": "2025-07-01T00:00:00Z"},
                        {"field": "created_at", "operator": "lt", "value": "2025-08-01T00:00:00Z"},
                    ]
                }
            ]
        },
    },
    limit=50,
)
for edge in edges:
    print(edge.fact, edge.created_at)

The date_filters object uses the same any_of/all_of structure as graph search: predicates inside one group are ANDed and groups are ORed. See Datetime Filtering for the full semantics.

Pagination

Each list method returns a page with items and next_cursor. The SDKs wrap the page in a pager that sends next_cursor as the cursor of the next request when you iterate past the current page. When next_cursor is absent, there are no more pages. The cursor is opaque. Do not make a cursor yourself, and do not change it.

To walk the pages one at a time, use the page accessors of the pager.

from zep_cloud.client import Zep
client = Zep(api_key=API_KEY)
all_nodes = []
for node in client.graph.node.list(graph_uuid, limit=100):
    all_nodes.append(node)

Listing observations and thread summaries

Observations and thread summaries use the same shared parameters.

# Observations in a graph.
observations = client.graph.observation.list(graph_uuid, limit=20)
# Thread summaries across the threads of a user graph.
summaries = client.graph.thread_summary.list(graph_uuid, limit=20)

Read Observations and Thread summaries for details.

Document summaries apply to episodes grouped by document_id. List them with graph.document_summary.list.

Listing episodes

graph.episode.list takes the same limit and cursor parameters as the other artifact types, and returns the newest episodes first. Use it to walk every episode in a graph in stable pages. See Pagination.

The episode list accepts two filter keys only: mentioned_node_uuids, which restricts results to episodes mentioning any of the listed entities, and metadata_filters, which restricts results to episodes whose stored metadata matches the same predicate used by graph search.

# Episodes that mention a given entity.
episodes = client.graph.episode.list(
    graph_uuid,
    filters={"mentioned_node_uuids": [node_uuid]},
    limit=50,
)
for episode in episodes:
    print(episode.uuid_, episode.created_at)

Navigating the graph

Listing walks a graph by artifact type. Navigation walks it by connection: start from a node and pull what it is attached to. When the API key has no active attribute constraints, both methods include the connecting edges’ endpoint names and labels (source_node_name, target_node_name, source_node_labels, target_node_labels), avoiding separate endpoint-node reads. With active attribute constraints, Zep omits these four fields and retains the endpoint UUIDs.

Neighbors of a node

graph.node.list_neighbors returns each distinct node connected to an anchor node, together with every edge that connects it to the anchor. Results paginate by neighbor node with the same pager as the list methods (see Pagination).

neighbors = client.graph.node.list_neighbors(
    graph_uuid,
    node_uuid,
    direction="both",
    limit=25,
)
for neighbor in neighbors:
    print(neighbor.node.name, len(neighbor.edges))

Bounded subgraphs

graph.get_subgraph expands breadth-first from up to 20 seed nodes and returns the resulting neighborhood as a single {nodes, edges} payload. Every edge’s endpoints are present in nodes, so the response is a self-contained graph you can render directly. It is built for agent exploration and visualization, not for exporting a graph. Use the list methods for that.

When a budget stops the expansion, the response sets truncated to true and names the binding limit in truncation_reason (for example max_nodes or max_edges), so a partial neighborhood is never mistaken for a complete one.

subgraph = client.graph.get_subgraph(
    graph_uuid,
    seed_node_uuids=[node_uuid],
    depth=2,
    max_nodes=200,
)
print(len(subgraph.nodes), len(subgraph.edges))
if subgraph.truncated:
    print("truncated by:", subgraph.truncation_reason)

Reads by node or episode

To read the items that are connected to one node or one episode, use a list method with a filter:

Related

• Searching the graph — rank artifacts by relevance to a query, including the full SearchFilters reference.
• Entities, Facts, Observations, and Thread summaries — per-type detail for each artifact.