Search Graph | Zep Documentation

from zep_cloud import Zep
client = Zep(
    api_key="YOUR_API_KEY",
)
client.graph.search(
    query="query",
)

{
  "context": "string",
  "edges": [
    {
      "created_at": "string",
      "fact": "string",
      "name": "string",
      "source_node_uuid": "string",
      "target_node_uuid": "string",
      "uuid": "string",
      "attributes": {},
      "episodes": [
        "string"
      ],
      "expired_at": "string",
      "invalid_at": "string",
      "relevance": 1.1,
      "scope": "string",
      "score": 1.1,
      "selection_rank": 1,
      "valid_at": "string"
    }
  ],
  "episodes": [
    {
      "content": "string",
      "created_at": "string",
      "uuid": "string",
      "metadata": {},
      "processed": true,
      "relevance": 1.1,
      "role": "string",
      "role_type": "norole",
      "score": 1.1,
      "selection_rank": 1,
      "source": "text",
      "source_description": "string",
      "task_id": "string",
      "thread_id": "string"
    }
  ],
  "nodes": [
    {
      "created_at": "string",
      "name": "string",
      "summary": "string",
      "uuid": "string",
      "attributes": {},
      "labels": [
        "string"
      ],
      "relevance": 1.1,
      "score": 1.1,
      "selection_rank": 1
    }
  ],
  "observations": [
    {
      "created_at": "string",
      "name": "string",
      "uuid": "string",
      "attributes": {},
      "end_at": "string",
      "episode_ids": [
        "string"
      ],
      "labels": [
        "string"
      ],
      "latest_evidence_at": "string",
      "relevance": 1.1,
      "score": 1.1,
      "selection_rank": 1,
      "start_at": "string",
      "summary": "string"
    }
  ],
  "thread_summaries": [
    {
      "created_at": "string",
      "name": "string",
      "uuid": "string",
      "labels": [
        "string"
      ],
      "last_summarized_at": "string",
      "last_summarized_episode_valid_at": "string",
      "relevance": 1.1,
      "score": 1.1,
      "selection_rank": 1,
      "summary": "string"
    }
  ]
}

Perform a graph search query.

Request

Graph search query

querystringRequired<=400 characters

The string to search for (required)

bfs_origin_node_uuidslist of stringsOptional

Nodes that are the origins of the BFS searches

center_node_uuidstringOptional

Node to rerank around for node distance reranking

graph_idstringOptional

The graph_id to search in. When searching user graph, please use user_id instead.

limitintegerOptional<=50

The maximum number of facts to retrieve for non-auto scopes. Defaults to 10. Limited to 50. Ignored when scope=auto.

max_charactersintegerOptional1-50000

Maximum total characters across all selected results when scope=auto. Defaults to 2500. Limited to 50000.

mmr_lambdadoubleOptional

weighting for maximal marginal relevance

rerankerenumOptional

Defaults to RRF. Ignored when scope=auto except node_distance and episode_mentions are rejected; auto search always uses RRF retrieval and applies its own internal rerank after retrieval.

Allowed values:

return_raw_resultsbooleanOptional

When scope=auto, include the selected raw graph results alongside the materialized context block. For graph-service-backed auto mode, selected raw results may include episodes, edges, nodes, observations, and thread_summaries.

scopeenumOptional

Defaults to Edges.

search_filtersobjectOptional

Search filters to apply to the search

user_idstringOptional

The user_id when searching user graph. If not searching user graph, please use graph_id instead.

Response

Graph search results or auto-context block

contextstring

edgeslist of objects

episodeslist of objects

nodeslist of objects

observationslist of objects

thread_summarieslist of objects

Errors

400

Bad Request Error

500

Internal Server Error