> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs-beta.getzep.com/v4/sdk-reference/graph/get-subgraph/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-beta.getzep.com/_mcp/server. # Get subgraph POST https://api.getzep.com/api/v4/graphs/{graph_uuid}/subgraph Content-Type: application/json Reference: https://docs-beta.getzep.com/sdk-reference/graph/get-subgraph ## Authentication - `Authorization` header (required) (prefixed with ` Api-Key `) — Type "Api-Key" followed by a space and the project API key. ## Request ### Path parameters - `graph_uuid` (string, required) — Graph UUID ### Body (application/json) This endpoint expects a v4.SubgraphRequest. - `seed_node_uuids` (list of string, required) — The node UUIDs to expand from, in traversal-priority order. - `depth` (integer, optional) — The maximum traversal depth from the seed nodes. Defaults to 1. - `direction` (enum, optional) — The edge orientation to follow during expansion: in, out, or both. Defaults to both. - Allowed values: `in`, `out`, `both` - `filters` (v4.SearchFilters, optional) — Filters constraining the traversed edges and included nodes. - `max_edges` (integer, optional) — The maximum number of edges in the response. Defaults to 200. - `max_nodes` (integer, optional) — The maximum number of nodes in the response. Defaults to 100. ## Response ### 200 OK - `edges` (list of v4.Edge, optional) — Every traversed edge that passed the request filters; both endpoints of every edge are present in nodes. - `nodes` (list of v4.Node, optional) — Every admitted seed node and every node reached within the traversal budget. - `truncated` (boolean, optional) — Whether any budget or limit reduced the result. - `truncation_reason` (string, optional) — The binding limit that caused truncation, such as max_nodes or max_edges; present only when truncated is true. ## 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) ## Types ### v4.SearchFilters - `connected_node_uuids` (list of string, optional) — Include edges connected to any of these node UUIDs. - `content_policy_violated` (boolean, optional) — Match episodes by their content-policy result. Supported only on episode search when the project setting include_policy_violating_episodes is true. - `date_filters` (v4.DateFilters, optional) — Filter results by temporal values. - `edge_types` (list of string, optional) — Include results with any of these edge types. - `edge_uuids` (list of string, optional) — Include results with any of these edge UUIDs. - `episode_uuids` (list of string, optional) — Include results derived from any of these episode UUIDs. - `exclude_edge_types` (list of string, optional) — Exclude results with any of these edge types. - `exclude_node_labels` (list of string, optional) — Exclude results with any of these node labels. - `metadata_filters` (v4.MetadataFilterGroup, optional) — Filter results by episode metadata. - `node_labels` (list of string, optional) — Include results with any of these node labels. - `property_filters` (list of v4.PropertyFilter, optional) — Filter results by node or edge properties. - `source_node_uuids` (list of string, optional) — Include edges that start at any of these node UUIDs. - `target_node_uuids` (list of string, optional) — Include edges that end at any of these node UUIDs. ### 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. - `uuid` (string, optional) — The unique identifier of the edge. - `valid_at` (string, optional) — The time from which the fact is considered true. ### 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. - `uuid` (string, optional) — The node UUID, assigned by Zep. ### v4.ErrorBody - `code` (string, optional) - `details` (map from string to any, optional) - `message` (string, optional) - `param` (string, optional) - `request_id` (string, optional) ### v4.DateFilters - `any_of` (list of v4.DateFilterGroup, optional) — Each group is combined with OR logic. ### v4.MetadataFilterGroup - `filters` (list of v4.MetadataFilter, optional) — The metadata predicates in this group. - `groups` (list of v4.MetadataFilterGroup, optional) — The nested metadata groups in this group. - `type` (enum, optional) — The logical operator for this group. - Allowed values: `and`, `or` ### v4.PropertyFilter - `operator` (enum, optional) — The lowercase comparison operator. - Allowed values: `eq`, `ne`, `gt`, `lt`, `gte`, `lte`, `in`, `is_null`, `is_not_null` - `property_name` (string, optional) — The property name to compare. - `value` (V4PropertyFilterValue, optional) — The comparison value. Use an array for in. Its string members must be non-empty, contain no comma, and have no surrounding whitespace. ### v4.DateFilterGroup - `all_of` (list of v4.DateFilter, optional) — All conditions in the group must match. ### v4.MetadataFilter - `operator` (enum, optional) — The lowercase comparison operator. - Allowed values: `eq`, `ne`, `gt`, `lt`, `gte`, `lte`, `in`, `contains`, `is_null`, `is_not_null` - `property_name` (string, optional) — The metadata property name to compare. - `value` (V4MetadataFilterValue, optional) — The comparison value. Use an array for in, a non-empty string for contains, and omit the field for null operators. ### V4PropertyFilterValue The comparison value. Use an array for in. Its string members must be non-empty, contain no comma, and have no surrounding whitespace. ### v4.DateFilter - `field` (enum, optional) — The temporal field to compare. - Allowed values: `created_at`, `valid_at`, `invalid_at`, `expired_at` - `operator` (enum, optional) — The lowercase comparison operator. - Allowed values: `eq`, `ne`, `gt`, `lt`, `gte`, `lte`, `is_null`, `is_not_null` - `value` (string, optional) — The RFC 3339 timestamp. Omit this field for null operators. ### V4MetadataFilterValue The comparison value. Use an array for in, a non-empty string for contains, and omit the field for null operators. ## Examples **Request** ```json { "seed_node_uuids": [ "string" ] } ``` **Response** ```json { "edges": [ { "attributes": {}, "created_at": "string", "episode_uuids": [ "string" ], "expired_at": "string", "fact": "string", "graph_uuid": "string", "hyperedge_uuid": "string", "invalid_at": "string", "name": "string", "relevance": 1.1, "scope": "string", "score": 1.1, "source_node_labels": [ "string" ], "source_node_name": "string", "source_node_uuid": "string", "target_node_labels": [ "string" ], "target_node_name": "string", "target_node_uuid": "string", "uuid": "string", "valid_at": "string" } ], "nodes": [ { "episode_uuids": [ "string" ], "episode_uuids_truncated": true, "attributes": {}, "created_at": "string", "degree": 1, "graph_uuid": "string", "labels": [ "string" ], "name": "string", "relevance": 1.1, "score": 1.1, "summary": "string", "uuid": "string" } ], "truncated": true, "truncation_reason": "string" } ```