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

# Querying a Graph

> **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](mailto: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`.

**`Python`**

```python Python
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)
```

**`TypeScript`**

```typescript TypeScript
import { ZepClient } from "@getzep/zep-cloud";

const client = new ZepClient({
  apiKey: API_KEY,
});

const response = await client.graph.query({
  graphUuids: [graphUuid],
  query: "Which companies acquired a logistics company in 2024?",
  mode: "deep",
  generateAnswer: true,
});
console.log(response.answer);
```

**`Go`**

```go Go
import (
	"context"
	"fmt"

	zep "github.com/getzep/zep-go/v4"
	zepclient "github.com/getzep/zep-go/v4/client"
	"github.com/getzep/zep-go/v4/option"
)

func queryGraph(ctx context.Context, apiKey, graphUUID string) (*zep.GraphQueryResponse, error) {
	client := zepclient.NewClient(
		option.WithAPIKey(apiKey),
	)

	generateAnswer := true
	response, err := client.Graph.Query(ctx, &zep.GraphQueryRequest{
		GraphUUIDs:     []string{graphUUID},
		Query:          "Which companies acquired a logistics company in 2024?",
		Mode:           zep.GraphQueryRequestModeDeep.Ptr(),
		GenerateAnswer: &generateAnswer,
	})
	if err != nil {
		return nil, err
	}
	fmt.Println(*response.Answer)
	return response, nil
}
```

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