> 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. Retrieves the graph records for a natural-language question about a graph with a read-only retrieval loop. By default, the response has the retrieved records and no answer. Set `generate_answer` to `true` to also get an answer that a model writes from the records, with the cited graph items. Set `stream` to `true` to get the retrieval calls as server-sent events. The default mode is fast. fast: A decision model selects the types of search for each round and stops when it has enough context. The query runs at most 3 search rounds. deep: A model plans its own searches. It can page through complete lists and read more records before it answers. A project with a BYOM configuration supports only deep. A BYOC deployment supports only deep. The operation is experimental and in closed release. Zep enables the operation only for select accounts. The request, the response, the events, and the modes of the operation can change. 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` (true, required) — When true, return the retrieval calls as server-sent events.
- `generate_answer` (boolean, optional) — When true, a model also writes an answer from the retrieved records. The default is false: the response has the records and no answer.
- `guidance` (string, optional) — Optional caller guidance for the answer. The agent treats it as untrusted text.
- `mode` (enum, optional) — The retrieval mode. The default is fast. fast: A decision model selects the types of search for each round and stops when it has enough context. The query runs at most 3 search rounds. deep: A model plans its own searches. It can page through complete lists and read more records before it answers. A project with a BYOM configuration supports only deep. A BYOC deployment supports only deep.
  - Allowed values: `fast`, `deep`

## Response

### 200

- Streaming response of `GraphQueryStreamEvent`.
- `type`: `started` (started)
  - `graph_uuids` (list of string, required)
  - `handles` (list of GraphQueryHandle, required)
  - `sequence` (integer, required)
- `type`: `reasoning` (reasoning)
  - `sequence` (integer, required)
  - `step` (integer, required)
  - `text` (string, required)
- `type`: `plan` (plan)
  - `plan` (GraphQueryPlan, required)
  - `revision` (integer, required)
  - `sequence` (integer, required)
  - `step` (integer, required)
- `type`: `tool_call` (tool_call)
  - `arguments` (string, required)
  - `call_number` (integer, required)
  - `sequence` (integer, required)
  - `step` (integer, required)
  - `tool` (string, required)
- `type`: `tool_result` (tool_result)
  - `call_number` (integer, required)
  - `duration_ms` (long, required)
  - `handles` (list of GraphQueryHandle, required)
  - `results` (v4.GraphQueryResults, required)
  - `sequence` (integer, required)
  - `tool` (string, required)
  - `listing` (GraphQueryListing, optional)
- `type`: `tool_error` (tool_error)
  - `call_number` (integer, required)
  - `duration_ms` (long, required)
  - `reason` (enum, required)
    - Allowed values: `invalid_arguments`, `duplicate_call`, `unknown_tool`, `plan_limit`, `retrieval_failed`
  - `sequence` (integer, required)
  - `tool` (string, required)
- `type`: `result` (result)
  - `citations` (v4.GraphQueryCitations, required)
  - `results` (v4.GraphQueryResults, required)
  - `sequence` (integer, required)
  - `truncated` (boolean, required)
  - `answer` (string, optional)
- `type`: `error` (error)
  - `error` (v4.ErrorBody, required)
  - `sequence` (integer, required)
  - `status` (integer, required)

## 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)

### 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

### GraphQueryHandle

- `handle` (string, required)
- `item_type` (enum, required)
  - Allowed values: `node`, `edge`, `episode`
- `uuid` (string, required)
- `graph_uuid` (string, required)

### GraphQueryPlan

- `subjects` (list of string, required)
- `steps` (list of GraphQueryPlanStep, required)
- `evidence_needed` (list of string, required)
- `stop_when` (string, required)
- `answer_language` (string, required)

### v4.GraphQueryResults

- `edges` (list of v4.GraphQueryEdge, optional) — The retrieved edges.
- `episodes` (list of v4.Episode, optional) — The retrieved episodes.
- `nodes` (list of v4.GraphQueryNode, optional) — The retrieved nodes.
- `observations` (list of v4.Observation, optional) — The retrieved observations.
- `thread_summaries` (list of v4.ThreadSummary, optional) — The retrieved thread summaries.

### GraphQueryListing

- `first_item` (integer, required)
- `last_item` (integer, required)
- `complete` (boolean, required)

### 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.ErrorBody

- `code` (string, optional)
- `details` (map from string to any, optional)
- `message` (string, optional)
- `param` (string, optional)
- `request_id` (string, optional)

### GraphQueryPlanStep

- `tool` (string, required)
- `purpose` (string, required)
- `arguments_hint` (string, required)

### v4.GraphQueryEdge

- `attributes` (map from string to any, optional) — Additional attributes of the edge.
- `created_at` (string, optional) — The time the edge was created.
- `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.
- `scope` (string, optional) — The kind of edge this is, for example entity or episodic.
- `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.GraphQueryNode

- `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.
- `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.
- `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
}
```