> 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. # List episode ingestion traces GET https://api.getzep.com/api/v4/graphs/{graph_uuid}/episodes/{episode_uuid}/ingestion-traces Returns the ingestion traces of an episode, oldest first. Each trace records the input and the output of one ingestion step, with an explanation on each output entry that has one. Traces exist only when ingestion tracing was enabled for the project when the episode was ingested (see `debug_log.enable`). An episode with no traces returns a page with an empty `items` array. Traces hold episode content, prompt input, and model output, so an API key with an ABAC policy needs an explicit grant of this action; the `readonly` macro does not grant it. Reference: https://docs-beta.getzep.com/sdk-reference/graph/episode/list-ingestion-traces ## 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 - `episode_uuid` (string, required) — Episode UUID ### Query parameters - `limit` (integer, optional) — Page size - `cursor` (string, optional) — Opaque page cursor ## Response ### 200 OK - `items` (list of v4.IngestionTrace, optional) — The ingestion traces on this page. - `next_cursor` (string, optional) — The cursor to pass as the next request's cursor to fetch the following page; absent when no further pages remain. ## 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.IngestionTrace - `created_at` (string, optional) — The time the trace was recorded. - `error` (string, optional) — The error message, present only when the status is failed. - `input` (v4.IngestionTraceInput, optional) — The input of the step. - `output` (v4.IngestionTraceOutput, optional) — The output of the step, with an explanation on each entry that has one. - `status` (enum, optional) — Tells if the explanations of the step were recorded. - Allowed values: `recorded`, `failed` - `step` (enum, optional) — The ingestion step that the trace records. - Allowed values: `combined_extraction`, `resolve_nodes`, `resolve_edges` - `uuid` (string, optional) — The unique identifier of the trace. ### v4.ErrorBody - `code` (string, optional) - `details` (map from string to any, optional) - `message` (string, optional) - `param` (string, optional) - `request_id` (string, optional) ### v4.IngestionTraceInput - `candidate_edges` (list of v4.IngestionTraceEdge, optional) — The existing edges that the step compared with the extracted edges. Present for resolve_edges and empty for the other steps. - `candidate_nodes` (list of v4.IngestionTraceNode, optional) — The existing nodes that the step compared with the extracted nodes. Present for resolve_nodes and empty for the other steps. - `custom_instructions` (list of string, optional) — The custom extraction instructions in effect for the episode. - `edge_types` (list of v4.EdgeType, optional) — The custom edge types in effect for the episode. - `entity_types` (list of v4.IngestionTraceEntityType, optional) — The custom entity types in effect for the episode. - `episode_content` (string, optional) — The content of the episode that the step processed. - `episodes` (list of v4.IngestionTraceEpisode, optional) — The episodes that the step processed together. - `extracted_edges` (list of v4.IngestionTraceEdge, optional) — The extracted edges that the step resolved. Present for resolve_edges and empty for the other steps. - `extracted_nodes` (list of v4.IngestionTraceNode, optional) — The extracted nodes that the step resolved. Present for resolve_nodes and empty for the other steps. - `ignore_default_ontology` (boolean, optional) — Tells if the default ontology was ignored. - `previous_episodes` (list of v4.IngestionTraceEpisode, optional) — The previous episodes that the step used as context. - `resolved_nodes` (list of v4.IngestionTraceNode, optional) — The resolved nodes that the extracted edges connect. Present for resolve_edges and empty for the other steps. ### v4.IngestionTraceOutput - `edge_invalidations` (list of v4.IngestionTraceEdgeInvalidation, optional) — The existing edges that the resolved edges invalidated. Present for resolve_edges and empty for the other steps. - `edges` (list of v4.IngestionTraceEdge, optional) — The resolved edges. Present for resolve_edges and empty for the other steps. - `extracted_edges` (list of v4.IngestionTraceEdge, optional) — The edges that the step extracted. Present for combined_extraction and empty for the other steps. - `extracted_nodes` (list of v4.IngestionTraceNode, optional) — The nodes that the step extracted. Present for combined_extraction and empty for the other steps. - `new_edges` (list of v4.IngestionTraceEdge, optional) — The resolved edges that are new to the graph. Present for resolve_edges and empty for the other steps. - `node_duplicates` (list of v4.IngestionTraceNodeDuplicate, optional) — The extracted nodes that the step found to be duplicates of existing nodes. Present for resolve_nodes and empty for the other steps. - `node_resolutions` (list of v4.IngestionTraceNodeResolution, optional) — The resolved node of each extracted node. Present for resolve_nodes and empty for the other steps. - `nodes` (list of v4.IngestionTraceNode, optional) — The resolved nodes. Present for resolve_nodes and empty for the other steps. ### v4.IngestionTraceEdge - `attributes` (map from string to any, optional) — Additional attributes of the edge, as defined by its edge type. - `created_at` (string, optional) — The time the edge was created. - `episode_uuids` (list of string, optional) — The episodes that the edge was derived from. - `expired_at` (string, optional) — The time the edge was superseded. - `explanation` (string, optional) — The explanation of the decision of the step for this edge. Present only on output entries that have an explanation. - `fact` (string, optional) — The natural-language fact that the edge represents. - `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. - `source_node_uuid` (string, optional) — The unique identifier of the source node of the edge. - `target_node_uuid` (string, optional) — The unique identifier of the target node of the edge. - `uuid` (string, optional) — The unique identifier of the edge. - `valid_at` (string, optional) — The time from which the fact is true. ### v4.IngestionTraceNode - `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. - `episode_indexes` (list of integer, optional) — The positions in the input episodes of the episodes that the node was extracted from. Present on the extracted nodes of combined_extraction. - `explanation` (string, optional) — The explanation of the decision of the step for this node. Present only on output entries that have an explanation. - `labels` (list of string, optional) — The entity type labels of the node. - `name` (string, optional) — The name of the entity that the node represents. - `summary` (string, optional) — The summary of the entity that the node represents. - `uuid` (string, optional) — The unique identifier of the node. ### v4.EdgeType - `description` (string, optional) — A description of the relationship this edge type represents, used to guide extraction. - `name` (string, optional) — The name of the edge type, in upper snake case. - `properties` (list of v4.EntityProperty, optional) — The custom properties defined on edges of this type. - `source_targets` (list of v4.EdgeSourceTarget, optional) — The allowed source and target entity type pairs for edges of this type. ### v4.IngestionTraceEntityType - `description` (string, optional) — A description of the entity type, used to guide extraction. - `identity_properties` (list of string, optional) — The property names that determine whether two nodes of this type are the same entity. - `name` (string, optional) — The name of the entity type. - `parent` (string, optional) — The name of the parent entity type. Absent for a top-level type. - `properties` (list of v4.EntityProperty, optional) — The custom properties defined on nodes of this type. ### v4.IngestionTraceEpisode - `content` (string, optional) — The content of the episode. - `source` (string, optional) — The source type of the episode, for example message, text, or json. - `uuid` (string, optional) — The unique identifier of the episode. - `valid_at` (string, optional) — The time at which the episode occurred. ### v4.IngestionTraceEdgeInvalidation - `invalidated_edge_uuid` (string, optional) — The unique identifier of the invalidated edge. - `invalidating_edges` (list of v4.IngestionTraceEdgeReference, optional) — The resolved edges that invalidated the edge. ### v4.IngestionTraceNodeDuplicate - `existing_node` (v4.IngestionTraceNode, optional) — The existing node that the extracted node duplicates. - `extracted_node` (v4.IngestionTraceNode, optional) — The extracted node. ### v4.IngestionTraceNodeResolution - `explanation` (string, optional) — The explanation of the decision, when the step recorded one. - `extracted_node_uuid` (string, optional) — The unique identifier of the extracted node. - `resolved_node_uuid` (string, optional) — The unique identifier of the resolved node. ### v4.EntityProperty - `description` (string, optional) — A description of the property, used to guide extraction. - `name` (string, optional) — The name of the property. - `type` (enum, optional) — The value type of the property: text, int, float, or boolean. - Allowed values: `text`, `int`, `float`, `boolean` ### v4.EdgeSourceTarget - `source` (string, optional) — The entity type an edge of this type originates from. - `target` (string, optional) — The entity type an edge of this type points to. ### v4.IngestionTraceEdgeReference - `explanation` (string, optional) — The explanation of the decision, when the step recorded one. - `uuid` (string, optional) — The unique identifier of the edge. ## Examples **Response** ```json { "items": [ { "created_at": "string", "error": "string", "input": { "candidate_edges": [ { "attributes": {}, "created_at": "string", "episode_uuids": [ "string" ], "expired_at": "string", "explanation": "string", "fact": "string", "invalid_at": "string", "name": "string", "source_node_uuid": "string", "target_node_uuid": "string", "uuid": "string", "valid_at": "string" } ], "candidate_nodes": [ { "attributes": {}, "created_at": "string", "episode_indexes": [ 1 ], "explanation": "string", "labels": [ "string" ], "name": "string", "summary": "string", "uuid": "string" } ], "custom_instructions": [ "string" ], "edge_types": [ { "description": "string", "name": "string", "properties": [ { "description": "string", "name": "string", "type": "text" } ], "source_targets": [ { "source": "string", "target": "string" } ] } ], "entity_types": [ { "description": "string", "identity_properties": [ "string" ], "name": "string", "parent": "string", "properties": [ { "description": "string", "name": "string", "type": "text" } ] } ], "episode_content": "string", "episodes": [ { "content": "string", "source": "string", "uuid": "string", "valid_at": "string" } ], "extracted_edges": [ { "attributes": {}, "created_at": "string", "episode_uuids": [ "string" ], "expired_at": "string", "explanation": "string", "fact": "string", "invalid_at": "string", "name": "string", "source_node_uuid": "string", "target_node_uuid": "string", "uuid": "string", "valid_at": "string" } ], "extracted_nodes": [ { "attributes": {}, "created_at": "string", "episode_indexes": [ 1 ], "explanation": "string", "labels": [ "string" ], "name": "string", "summary": "string", "uuid": "string" } ], "ignore_default_ontology": true, "previous_episodes": [ { "content": "string", "source": "string", "uuid": "string", "valid_at": "string" } ], "resolved_nodes": [ { "attributes": {}, "created_at": "string", "episode_indexes": [ 1 ], "explanation": "string", "labels": [ "string" ], "name": "string", "summary": "string", "uuid": "string" } ] }, "output": { "edge_invalidations": [ { "invalidated_edge_uuid": "string", "invalidating_edges": [ { "explanation": "string", "uuid": "string" } ] } ], "edges": [ { "attributes": {}, "created_at": "string", "episode_uuids": [ "string" ], "expired_at": "string", "explanation": "string", "fact": "string", "invalid_at": "string", "name": "string", "source_node_uuid": "string", "target_node_uuid": "string", "uuid": "string", "valid_at": "string" } ], "extracted_edges": [ { "attributes": {}, "created_at": "string", "episode_uuids": [ "string" ], "expired_at": "string", "explanation": "string", "fact": "string", "invalid_at": "string", "name": "string", "source_node_uuid": "string", "target_node_uuid": "string", "uuid": "string", "valid_at": "string" } ], "extracted_nodes": [ { "attributes": {}, "created_at": "string", "episode_indexes": [ 1 ], "explanation": "string", "labels": [ "string" ], "name": "string", "summary": "string", "uuid": "string" } ], "new_edges": [ { "attributes": {}, "created_at": "string", "episode_uuids": [ "string" ], "expired_at": "string", "explanation": "string", "fact": "string", "invalid_at": "string", "name": "string", "source_node_uuid": "string", "target_node_uuid": "string", "uuid": "string", "valid_at": "string" } ], "node_duplicates": [ { "existing_node": { "attributes": {}, "created_at": "string", "episode_indexes": [ 1 ], "explanation": "string", "labels": [ "string" ], "name": "string", "summary": "string", "uuid": "string" }, "extracted_node": { "attributes": {}, "created_at": "string", "episode_indexes": [ 1 ], "explanation": "string", "labels": [ "string" ], "name": "string", "summary": "string", "uuid": "string" } } ], "node_resolutions": [ { "explanation": "string", "extracted_node_uuid": "string", "resolved_node_uuid": "string" } ], "nodes": [ { "attributes": {}, "created_at": "string", "episode_indexes": [ 1 ], "explanation": "string", "labels": [ "string" ], "name": "string", "summary": "string", "uuid": "string" } ] }, "status": "recorded", "step": "combined_extraction", "uuid": "string" } ], "next_cursor": "string" } ```