SDK ReferenceGraphEpisode

List Graph Episodes

Returns a paginated, filterable list of episodes for a graph.

Path parameters

graph_idstringRequired
Graph ID

Request

Episode listing request
cursorstringOptional

Opaque cursor for pagination, obtained from the Zep-Next-Cursor response header of the previous page.

directionstringOptional
Sort direction. One of "asc" or "desc". Defaults to "desc".
limitintegerOptional

Maximum number of episodes to return. An explicit value is clamped to 50; when omitted, the default page size (100) applies.

mentioned_node_uuidslist of stringsOptional

Restricts results to episodes that mention any of the listed node UUIDs. At most 256 entries; each must be a syntactically valid UUID.

order_bystringOptional

Field to sort by. One of “uuid” or “created_at”. Defaults to “uuid”.

Response headers

Zep-Next-CursorstringOptional

Opaque cursor for the next page of results; absent when there are no more results.

Response

Episodes
contentstring
created_atstring
uuidstring
metadatamap from strings to anyOptional
processedbooleanOptional
relevancedoubleOptional

Relevance is an experimental rank-aligned score in [0,1] derived from Score via logit transformation. Only populated when using cross_encoder reranker; omitted for other reranker types (e.g., RRF).

rolestringOptional
Optional role, will only be present if the episode was created using memory.add API
role_typeenumOptional

Optional role_type, will only be present if the episode was created using memory.add API

scoredoubleOptional

Score is the reranker output: sigmoid-distributed logits [0,1] when using cross_encoder reranker, or RRF ordinal rank when using rrf reranker

selection_rankintegerOptional

SelectionRank is the global cross-scope rank assigned by auto scope selection.

sourceenumOptional
source_descriptionstringOptional
task_idstringOptional
Optional task ID to poll episode processing status. Currently only available for batch ingestion.
thread_idstringOptional
Optional thread ID, will be present if the episode is part of a thread

Errors

400
Bad Request Error
500
Internal Server Error