Querying a Graph | Zep Documentation

Experimental API

graph.query 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.

graph.query takes a natural-language question about one graph. The operation runs a read-only retrieval loop. The response contains at most 300 records in results. When the query returns more than 300 records, the server keeps cited records first in citation order. The server then keeps other records in the order that retrieval calls first returned them. The response sets truncated to true when the server omits records.

By default, the response has the records and no answer. When the request sets generate_answer to true, the response also includes an answer that a model writes from the records and citations to the graph items.

Select a mode

The mode field selects the retrieval loop. The default is fast.

Mode	What the query does
`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 value other than fast or deep returns 400 invalid_request with param set to mode.

from zep_cloud import Zep
client = Zep(
    api_key=API_KEY,
)
response = client.graph.query(
    graph_uuids=[graph_uuid],
    query="Which companies acquired a logistics company in 2024?",
    mode="deep",
    generate_answer=True,
)
print(response.answer)
for edge in response.results.edges:
    print(edge.fact)

BYOM and BYOC

fast mode uses a Zep decision model. It does not support BYOM configurations or BYOC deployments.

When the project has a BYOM configuration, set mode to deep. All model calls of the query then go to your BYOM provider. A fast request returns 409 conflict with the message “Fast mode does not support BYOM configurations. Set mode to deep.”
In a BYOC deployment, set mode to deep. A fast request returns 409 conflict with the message “Fast mode is not available in a BYOC deployment. Set mode to deep.”
When the BYOM configuration has no compatible model, a deep request returns 409 conflict.