> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-beta.getzep.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-beta.getzep.com/_mcp/server.

# Search Graph

POST https://api.getzep.com/api/v2/graph/search
Content-Type: application/json

Perform a graph search query.

Reference: https://docs-beta.getzep.com/sdk-reference/graph/search

## Request

### Body (application/json)

This endpoint expects a graphiti.GraphSearchQuery.

- `query` (string, required) — The string to search for (required)
- `bfs_origin_node_uuids` (list of string, optional) — Nodes that are the origins of the BFS searches
- `center_node_uuid` (string, optional) — Node to rerank around for node distance reranking
- `group_id` (string, optional) — one of user_id or group_id must be provided
- `limit` (integer, optional) — The maximum number of facts to retrieve. Defaults to 10. Limited to 50.
- `min_fact_rating` (double, optional) — The minimum rating by which to filter relevant facts
- `min_score` (double, optional) — Deprecated
- `mmr_lambda` (double, optional) — weighting for maximal marginal relevance
- `reranker` (enum, optional) — Defaults to RRF
  - Allowed values: `rrf`, `mmr`, `node_distance`, `episode_mentions`, `cross_encoder`
- `scope` (enum, optional) — Defaults to Edges. Communities will be added in the future.
  - Allowed values: `edges`, `nodes`, `episodes`
- `search_filters` (graphiti.SearchFilters, optional) — Search filters to apply to the search
- `user_id` (string, optional) — one of user_id or group_id must be provided

## Response

### 200

Graph search results

- `edges` (list of graphiti.EntityEdge, optional)
- `episodes` (list of apidata.GraphEpisode, optional)
- `nodes` (list of graphiti.EntityNode, optional)

## Errors

### 400 Bad Request Error

Bad Request

- `message` (string, optional)

### 500 Internal Server Error

Internal Server Error

- `message` (string, optional)

## Types

### graphiti.SearchFilters

- `created_at` (list of list of graphiti.DateFilter, optional) — 2D array of date filters for the created\_at field. The outer array elements are combined with OR logic. The inner array elements are combined with AND logic. Example: \[\[\{">", date1}, \{"\<", date2}], \[\{"=", date3}]] This translates to: (created\_at > date1 AND created\_at \< date2) OR (created\_at = date3)
- `edge_types` (list of string, optional) — List of edge types to filter on
- `expired_at` (list of list of graphiti.DateFilter, optional) — 2D array of date filters for the expired\_at field. The outer array elements are combined with OR logic. The inner array elements are combined with AND logic. Example: \[\[\{">", date1}, \{"\<", date2}], \[\{"=", date3}]] This translates to: (expired\_at > date1 AND expired\_at \< date2) OR (expired\_at = date3)
- `invalid_at` (list of list of graphiti.DateFilter, optional) — 2D array of date filters for the invalid\_at field. The outer array elements are combined with OR logic. The inner array elements are combined with AND logic. Example: \[\[\{">", date1}, \{"\<", date2}], \[\{"=", date3}]] This translates to: (invalid\_at > date1 AND invalid\_at \< date2) OR (invalid\_at = date3)
- `node_labels` (list of string, optional) — List of node labels to filter on
- `valid_at` (list of list of graphiti.DateFilter, optional) — 2D array of date filters for the valid\_at field. The outer array elements are combined with OR logic. The inner array elements are combined with AND logic. Example: \[\[\{">", date1}, \{"\<", date2}], \[\{"=", date3}]] This translates to: (valid\_at > date1 AND valid\_at \< date2) OR (valid\_at = date3)

### graphiti.EntityEdge

- `created_at` (string, required) — Creation time of the edge
- `fact` (string, required) — Fact representing the edge and nodes that it connects
- `name` (string, required) — Name of the edge, relation name
- `source_node_uuid` (string, required) — UUID of the source node
- `target_node_uuid` (string, required) — UUID of the target node
- `uuid` (string, required) — UUID of the edge
- `attributes` (map from string to any, optional) — Additional attributes of the edge. Dependent on edge types
- `episodes` (list of string, optional) — List of episode ids that reference these entity edges
- `expired_at` (string, optional) — Datetime of when the node was invalidated
- `invalid_at` (string, optional) — Datetime of when the fact stopped being true
- `valid_at` (string, optional) — Datetime of when the fact became true

### apidata.GraphEpisode

- `content` (string, required)
- `created_at` (string, required)
- `uuid` (string, required)
- `processed` (boolean, optional)
- `role` (string, optional) — Optional role, will only be present if the episode was created using memory.add API
- `role_type` (enum, optional) — Optional role_type, will only be present if the episode was created using memory.add API
  - Allowed values: `norole`, `system`, `assistant`, `user`, `function`, `tool`
- `session_id` (string, optional)
- `source` (enum, optional)
  - Allowed values: `text`, `json`, `message`
- `source_description` (string, optional)

### graphiti.EntityNode

- `created_at` (string, required) — Creation time of the node
- `name` (string, required) — Name of the node
- `summary` (string, required) — Regional summary of surrounding edges
- `uuid` (string, required) — UUID of the node
- `attributes` (map from string to any, optional) — Additional attributes of the node. Dependent on node labels
- `labels` (list of string, optional) — Labels associated with the node

### graphiti.DateFilter

- `comparison_operator` (enum, required) — Comparison operator for date filter
  - Allowed values: `=`, `<>`, `>`, `<`, `>=`, `<=`
- `date` (string, required) — Date to filter on

## Examples

**Request**

```json
{
  "query": "Find all connections related to project Apollo"
}
```

**Response**

```json
{
  "edges": [
    {
      "created_at": "2023-11-15T09:30:00Z",
      "fact": "Project Apollo is managed by the Space Exploration team.",
      "name": "managed_by",
      "source_node_uuid": "a3f1c9d0-4c5b-11ee-be56-0242ac120002",
      "target_node_uuid": "b4d2e1f3-4c5b-11ee-be56-0242ac120002",
      "uuid": "d9f1a2b3-4c5b-11ee-be56-0242ac120002",
      "attributes": {},
      "episodes": [
        "e7a1f3d2-4c5b-11ee-be56-0242ac120002"
      ],
      "expired_at": "2024-01-01T00:00:00Z",
      "invalid_at": "2023-12-31T23:59:59Z",
      "valid_at": "2023-10-01T00:00:00Z"
    }
  ],
  "episodes": [
    {
      "content": "Discussion about the management structure of Project Apollo.",
      "created_at": "2023-11-15T09:00:00Z",
      "uuid": "e7a1f3d2-4c5b-11ee-be56-0242ac120002",
      "processed": true,
      "role": "user",
      "role_type": "user",
      "session_id": "session-1234abcd",
      "source": "text",
      "source_description": "User query input"
    }
  ],
  "nodes": [
    {
      "created_at": "2023-10-01T08:00:00Z",
      "name": "Project Apollo",
      "summary": "A space exploration project managed by the Space Exploration team.",
      "uuid": "a3f1c9d0-4c5b-11ee-be56-0242ac120002",
      "attributes": {},
      "labels": [
        "Project",
        "SpaceExploration"
      ]
    }
  ]
}
```