Skip to navigation
SDK ReferenceGraphEpisode

List User Episodes

Returns a paginated, filterable list of episodes for a user’s graph.

Path parameters

user_idstringRequired
User 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".
episode_metadata_filtersobjectOptional

Restricts results to episodes whose stored metadata matches this predicate. Same type and limits as graph.search episode_metadata_filters.

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. The list can also contain episode UUIDs: an episode UUID matches that episode, so one request can return a known set of episodes. 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
document_idstringOptional
Optional document ID, will be present if the episode is part of a document
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
Allowed values:
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