Skip to navigation
SDK ReferenceGraph

Search episodes

Episode search supports only the metadata_filters and content_policy_violated filters. Every other filter returns unsupported_filter.

Authentication

AuthorizationApi-Key

Type “Api-Key” followed by a space and the project API key.

Path parameters

graph_uuidstringRequired
The UUID of the graph. For a user graph, you can also use the UUID of the user.

Query parameters

page_sizeintegerOptional1-50Defaults to 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. Search ranks a limited set of results, so iteration ends after that set. To get the top N results, set page_size to N and read the first page.

cursorstringOptional
Opaque page cursor

Request

Request body
querystringRequired
The search query.
bfs_origin_node_uuidslist of stringsOptional

Nodes used as BFS origins for graph-distance-aware retrieval.

center_node_uuidstringOptional

The node to rank results by distance from. Required when reranker is node_distance.

filter_low_quality_resultsbooleanOptional

The default is false. When true, Zep removes low-quality results at the knee of the cross-encoder score curve. The filter never removes a result with a score of 0.9 or more. It keeps at least 5 results, or all results when fewer than 5 are available. The filter only removes results, so a page still returns up to page_size results. Use this field only with reranker cross_encoder. It is not supported for episode search. Invalid combinations return a 400 error. The cutoff is approximate, not guaranteed. When the cross-encoder does not score the results, for example after a timeout, Zep returns the results without the filter.

filtersobjectOptional
Filters constraining which items are returned.
mmr_lambdadoubleOptional
The diversity weighting used for maximal marginal relevance reranking. Required when reranker is mmr.
rerankerenumOptional
The reranking strategy applied to retrieved results. Defaults to rrf.
Allowed values:

Response

OK
itemslist of objectsOptional
The episodes on this page.
next_cursorstringOptional
Opaque cursor for retrieving the next page, present only when more results are available.
total_sizeintegerOptional

Omitted for this collection; use next_cursor to detect the end of pagination.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error