> This page is for version v4 (default). > For other versions, use one of these documentation indexes: > - v4 (default): https://help.getzep.com/v4/llms.txt > - v3: https://help.getzep.com/v3/llms.txt > - v2: https://help.getzep.com/v2/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://help.getzep.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.getzep.com/_mcp/server. # Query a graph POST https://api.getzep.com/api/v4/graphs/query Content-Type: application/json Experimental. Answers a natural-language question about a graph with a read-only agent. Returns the answer, the cited graph items, and the graph records that the agent retrieved. Set `stream` to `true` to get the agent steps as server-sent events. The operation is experimental: its request, response, and events can change. Zep enables the operation for each account. A request from an account without access returns `404 not_found`. To get access, contact support@getzep.com. Reference: https://help.getzep.com/sdk-reference/graph/query ## Authentication - `Authorization` header (required) (prefixed with ` Api-Key `) — Type "Api-Key" followed by a space and the project API key. ## Request ### Body (application/json) This endpoint expects an object. - `graph_uuids` (list of string, required) — The graph UUIDs to query. The current release accepts one UUID. - `query` (string, required) — The natural-language question about the graph. - `stream` (false, required) — When true, return agent events as server-sent events. - `guidance` (string, optional) — Optional caller guidance for the answer. The agent treats it as untrusted text. ## Response ### 200 - `answer` (string, optional) — The final answer with citation handles removed. - `citations` (v4.GraphQueryCitations, optional) — The UUIDs of the graph items cited by the answer. - `results` (v4.GraphQueryResults, optional) — The distinct graph records retrieved during the query. - `truncated` (boolean, optional) — Whether the record limit omitted any results. ## Errors ### 400 Bad Request Error Bad Request - `error` (v4.ErrorBody, optional) ### 401 Unauthorized Error Unauthorized - `error` (v4.ErrorBody, optional) ### 403 Forbidden Error Forbidden - `error` (v4.ErrorBody, optional) ### 404 Not Found Error Not Found - `error` (v4.ErrorBody, optional) ### 409 Conflict Error Conflict - `error` (v4.ErrorBody, optional) ### 413 Content Too Large Error Request Entity Too Large - `error` (v4.ErrorBody, optional) ### 429 Too Many Requests Error Too Many Requests - `error` (v4.ErrorBody, optional) ### 500 Internal Server Error Internal Server Error - `error` (v4.ErrorBody, optional) ### 503 Service Unavailable Error Service Unavailable - `error` (v4.ErrorBody, optional) ## Types ### v4.GraphQueryCitations - `edge_uuids` (list of string, optional) — The edge UUIDs cited by the answer. - `episode_uuids` (list of string, optional) — The episode UUIDs cited by the answer. - `node_uuids` (list of string, optional) — The node UUIDs cited by the answer. ### v4.GraphQueryResults - `edges` (list of v4.Edge, optional) — The retrieved edges. - `episodes` (list of v4.Episode, optional) — The retrieved episodes. - `nodes` (list of v4.Node, optional) — The retrieved nodes. - `observations` (list of v4.Observation, optional) — The retrieved observations. - `thread_summaries` (list of v4.ThreadSummary, optional) — The retrieved thread summaries. ### v4.ErrorBody - `code` (string, optional) - `details` (map from string to any, optional) - `message` (string, optional) - `param` (string, optional) - `request_id` (string, optional) ### v4.Edge - `attributes` (map from string to any, optional) — Additional attributes of the edge. - `created_at` (string, optional) — The time the edge was created. - `episode_uuids` (list of string, optional) — The episodes this edge was derived from. - `expired_at` (string, optional) — The time the fact was superseded or removed. - `fact` (string, optional) — The natural-language fact this edge represents. - `graph_uuid` (string, optional) — The unique identifier of the graph this edge belongs to. - `hyperedge_uuid` (string, optional) — The unique identifier of the hyperedge this edge is a member of. Omitted when the edge is not part of a hyperedge. - `invalid_at` (string, optional) — The time at which the fact stopped being true. - `name` (string, optional) — The name of the edge, in upper snake case, for example RELATES_TO. - `relevance` (double, optional) — A cross-encoder-derived relevance score, present only when the cross-encoder reranker scored this result; like score, it is omitted from plain list results. - `scope` (string, optional) — The kind of edge this is, for example entity or episodic. - `score` (double, optional) — The ranking score returned with every search result; omitted when the edge appears in a plain list rather than a search result. - `source_node_labels` (list of string, optional) — The current labels of the source node. This is read at request time rather than stored on the edge, and is omitted when the source node cannot be resolved. - `source_node_name` (string, optional) — The current name of the source node. This is read at request time rather than stored on the edge, and is omitted when the source node cannot be resolved. - `source_node_uuid` (string, optional) — The unique identifier of the edge's source node. - `target_node_labels` (list of string, optional) — The current labels of the target node. This is read at request time rather than stored on the edge, and is omitted when the target node cannot be resolved. - `target_node_name` (string, optional) — The current name of the target node. This is read at request time rather than stored on the edge, and is omitted when the target node cannot be resolved. - `target_node_uuid` (string, optional) — The unique identifier of the edge's target node. - `user_uuid` (string, optional) — The unique identifier of the user that owns the graph. Present only when the graph is a user graph. - `uuid` (string, optional) — The unique identifier of the edge. - `valid_at` (string, optional) — The time from which the fact is considered true. ### v4.Episode - `content` (string, optional) — The raw content of the episode. - `content_policy` (v4.EpisodeContentPolicy, optional) — The content policy state of the episode, present only on a graph with a bound content policy rule. - `created_at` (string, optional) — The time Zep received the episode. - `document_id` (string, optional) — The developer-assigned identifier of the document this episode belongs to, present only for episodes added to a document. - `graph_uuid` (string, optional) — The unique identifier of the graph this episode belongs to. - `metadata` (map from string to any, optional) — Custom metadata associated with the episode. - `processed` (boolean, optional) — Whether the episode has finished graph extraction and indexing. - `reference_time` (string, optional) — The episode's reference time, used for temporal reasoning: the time that the developer supplied on add, or the ingestion time when the developer supplied no time. - `relevance` (double, optional) — A cross-encoder-derived relevance score, present only when the cross-encoder reranker scored this result; like score, it is omitted from plain list results. - `role` (enum, optional) — The role of the episode's sender, present only when the episode was added as a message. - Allowed values: `system`, `assistant`, `user`, `function`, `tool` - `role_name` (string, optional) — The free-form display name of the episode's sender, present only when the episode was added as a message. - `score` (double, optional) — The ranking score returned with every search result; omitted when the episode appears in a plain list rather than a search result. - `source` (enum, optional) — The format of the episode's content: text, json, or message. - Allowed values: `text`, `json`, `message`, `fact_triple` - `source_description` (string, optional) — A free-form description of where the episode's content came from. - `thread_uuid` (string, optional) — The thread this episode belongs to, present only for episodes added to a thread. - `user_uuid` (string, optional) — The unique identifier of the user that owns the graph. Present only when the graph is a user graph. - `uuid` (string, optional) — The unique identifier of the episode. ### v4.Node - `episode_uuids` (list of string, required) — The UUIDs of the live episodes that mention this node, newest first. The list is complete when `episode_uuids_truncated` is false. The list holds the newest 100 when the node has more than 100 source episodes; list episodes with the `mentioned_node_uuids` filter to read them all. - `episode_uuids_truncated` (boolean, required) — True when the node has more than 100 source episodes, so `episode_uuids` holds only the newest 100, or when provenance is unavailable. False means `episode_uuids` is the complete set. - `attributes` (map from string to any, optional) — Additional attributes of the node, as defined by its entity type. - `created_at` (string, optional) — The time the node was created. - `degree` (integer, optional) — The count of live entity edges that touch this node, in both directions. Present only when the list request orders by `degree`. - `graph_uuid` (string, optional) — The unique identifier of the graph this node belongs to. - `labels` (list of string, optional) — The entity type labels assigned to the node. - `name` (string, optional) — The name of the entity that the node represents. - `relevance` (double, optional) — A cross-encoder-derived relevance score, present only when the cross-encoder reranker scored this result; like score, it is omitted from plain list results. - `score` (double, optional) — The ranking score returned with every search result; omitted when the node appears in a plain list rather than a search result. - `summary` (string, optional) — A generated summary of the entity that the node represents. - `user_uuid` (string, optional) — The unique identifier of the user that owns the graph. Present only when the graph is a user graph. - `uuid` (string, optional) — The node UUID, assigned by Zep. ### v4.Observation - `attributes` (map from string to any, optional) — Additional attributes of the derived node, as defined by its entity type. - `created_at` (string, optional) — The time the observation was created. - `episode_uuids` (list of string, optional) — The unique identifiers of the episodes that support this observation. - `graph_uuid` (string, optional) — The unique identifier of the graph this observation belongs to. - `labels` (list of string, optional) — The labels identifying the type of this observation. - `name` (string, optional) — The name of the observation. - `relevance` (double, optional) — A cross-encoder-derived relevance score, present only when the cross-encoder reranker scored this result; like score, it is omitted from plain list results. - `score` (double, optional) — The ranking score returned with every search result; omitted when the observation appears in a plain list rather than a search result. - `summary` (string, optional) — A generated summary of the observation. - `user_uuid` (string, optional) — The unique identifier of the user that owns the graph. Present only when the graph is a user graph. - `uuid` (string, optional) — The unique identifier of the observation, assigned by Zep. ### v4.ThreadSummary - `created_at` (string, optional) — The time the summary was first created. - `graph_uuid` (string, optional) — The unique identifier of the graph this thread summary belongs to. - `last_summarized_at` (string, optional) — The wall-clock time of the most recent summary update. - `last_summarized_episode_valid_at` (string, optional) — The latest episode reference time covered by the most recent summary update. - `relevance` (double, optional) — A cross-encoder-derived relevance score, present only when the cross-encoder reranker scored this result; like score, it is omitted from plain list results. - `score` (double, optional) — A score accompanies every search result; it is omitted when the summary appears in a plain list rather than a search result. - `summary` (string, optional) — The generated summary text for the thread. - `thread_uuid` (string, optional) — The unique identifier of the thread this summary belongs to. - `uuid` (string, optional) — The unique identifier of the thread summary. ### v4.EpisodeContentPolicy - `category_keys` (list of string, optional) — The keys of the categories with a matched rule. - `dropped_count` (integer, optional) — The number of derived candidates that were dropped. - `retained_count` (integer, optional) — The number of derived candidates that were published to the graph. - `revision` (integer, optional) — The project revision number of the policy the graph bound. - `status` (enum, optional) — The evaluation status. pending means the evaluation has not finished, complete means every candidate was evaluated and the graph batch was written, and failed means ingestion retries were exhausted. - Allowed values: `pending`, `complete`, `failed` - `violated` (boolean, optional) — Whether at least one derived candidate matched a rule. Once true, it stays true. ## Examples **Request** ```json { "graph_uuids": [ "string" ], "query": "string", "stream": true } ```