> 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. # Create a trace import POST https://api.getzep.com/api/v4/agents/{agent_uuid}/trace-imports Content-Type: application/json Create a scheduled import or queue a one-time import. A scheduled import returns HTTP 201 with `import`. A one-time import returns HTTP 202 with `import`, `run`, and `task`. Example request: `{"connection_uuid":"8c78a85e-eac2-4f57-b5f5-59a68a1e77a1","provider_project_id":"project-123","name":"Support traces","selection":{"trace_ids":["trace-123"]},"mapping":{"task_family":{"source":"fixed","value":"support"}}}`. Reference: https://help.getzep.com/sdk-reference/agent/trace-imports/create ## Authentication - `Authorization` header (required) (prefixed with ` Api-Key `) — Type "Api-Key" followed by a space and the project API key. ## Request ### Path parameters - `agent_uuid` (string, required) — Agent UUID ### Body (application/json) This endpoint expects a v4.CreateTraceImportRequest. - `connection_uuid` (string, optional) — ConnectionUUID identifies the project trace connection. - `learn_from` (boolean, optional) — LearnFrom controls whether imported evidence can support Skills. - `mapping` (v4.TraceMapping, optional) — Mapping defines how source traces become Traces. Example: \{"task\_family":\{"source":"fixed","value":"support"}}. - `name` (string, optional) — Name is the import display name. - `on_source_change` (enum, optional) — OnSourceChange defines how changed source traces are handled. - Allowed values: `ignore`, `replace` - `provider_project_id` (string, optional) — ProviderProjectID is the source provider project identifier. - `require_review` (boolean, optional) — RequireReview requires review for candidates backed by this import. - `schedule` (v4.TraceImportSchedule, optional) — Schedule enables recurring imports when supplied. Example: \{"interval\_hours":4,"start\_from":"now","settle\_minutes":5,"max\_open\_hours":24}. - `selection` (v4.TraceImportSelection, optional) — Selection defines the traces to import. Example: \{"trace\_ids":\["trace\_123"]}. ## Response ### 201 Created - `import` (v4.TraceImport, optional) — Import is the created import resource. Example: \{"uuid":"332c28e1-e6a7-4bca-97b2-ef1ec82c65fa"}. - `run` (v4.TraceImportRun, optional) — Run is the pending one-time run. The field is absent for a scheduled import. Example: \{"uuid":"ea7e2724-9bfd-4ca1-aa5c-40a1dd72a688","status":"pending"}. - `task` (v4.Task, optional) — Task is the pending Task that will process the run. The field is absent for a scheduled import. Example: \{"uuid":"3124c01a-8f49-4bfd-9758-6ce491a377c1","status":"pending"}. ### 202 Accepted - `import` (v4.TraceImport, optional) — Import is the created import resource. Example: \{"uuid":"332c28e1-e6a7-4bca-97b2-ef1ec82c65fa"}. - `run` (v4.TraceImportRun, optional) — Run is the pending one-time run. The field is absent for a scheduled import. Example: \{"uuid":"ea7e2724-9bfd-4ca1-aa5c-40a1dd72a688","status":"pending"}. - `task` (v4.Task, optional) — Task is the pending Task that will process the run. The field is absent for a scheduled import. Example: \{"uuid":"3124c01a-8f49-4bfd-9758-6ce491a377c1","status":"pending"}. ## 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) ### 409 Conflict Error Conflict - `error` (v4.ErrorBody, optional) ### 422 Unprocessable Entity Error Unprocessable Entity - `error` (v4.ErrorBody, optional) ## Types ### v4.TraceMapping - `content` (v4.TraceContentMapping, optional) — Content configures copied span content. Example: \{"include\_system\_messages":false}. - `include_outcomes` (list of enum, optional) — IncludeOutcomes lists outcomes that can support a Skill. - Allowed values: `succeeded`, `failed`, `partial`, `abandoned`, `unknown` - `objective` (v4.ObjectiveMappingRule, optional) — Objective maps provider data to a Trace objective. Example: \{"source":"first\_user\_message"}. - `outcome` (list of v4.OutcomeMappingRule, optional) — Outcome contains ordered outcome mapping rules. Example: \[\{"rule":"score","name":"quality","succeeded\_at\_or\_above":0.8}]. - `score_verifier` (boolean, optional) — ScoreVerifier enables score-based verification. - `task_family` (v4.TaskFamilyMappingRule, optional) — TaskFamily maps provider data to a task family. Example: \{"source":"fixed","value":"support"}. ### v4.TraceImportSchedule - `interval_hours` (integer, required) — IntervalHours is the scheduled run interval. - `start_from` (string, required) — StartFrom is the earliest trace start time that scheduled runs import. The value is "now", which is the time when the import was created, or an RFC 3339 timestamp. - `max_open_hours` (integer, optional, default: 24) — MaxOpenHours is the maximum wait for an open trace. The value must be 1 to 168 hours. The default is 24 hours. - `settle_minutes` (integer, optional, default: 60) — SettleMinutes is the wait time for trace updates. The value must be 0 to 1,440 minutes. The default is 60 minutes. ### v4.TraceImportSelection - `filter` (v4.TraceFilter, optional) — Filter selects traces by provider fields. Example: \{"started\_after":"2026-01-01T00:00:00Z"}. - `trace_ids` (list of string, optional) — TraceIDs contains explicit provider trace identifiers. ### v4.TraceImport - `agent_uuid` (string, optional) — AgentUUID is the owning Agent identifier. - `connection_uuid` (string, optional) — ConnectionUUID is the trace connection identifier. - `created_at` (string, optional) — CreatedAt is the resource creation time. - `imported_trace_count` (integer, optional) — ImportedTraceCount is the number of Traces currently owned by this import. - `last_run` (v4.TraceImportRunReference, optional) — LastRun is the latest run for this import, when one exists. - `learn_from` (boolean, optional) — LearnFrom reports whether imported evidence can support Skills. - `mapping` (v4.TraceMapping, optional) — Mapping defines how traces become Traces. Example: \{"task\_family":\{"source":"fixed","value":"support"}}. - `name` (string, optional) — Name is the import display name. - `next_run_at` (string, optional) — NextRunAt is the next scheduled run time. - `on_source_change` (enum, optional) — OnSourceChange defines how changed source traces are handled. - Allowed values: `ignore`, `replace` - `pause_reason` (enum, optional) — PauseReason is the reason for a paused import, when present. - Allowed values: `user`, `credential_rejected`, `provider_project_not_found` - `provider` (enum, optional) — Provider is the Braintrust or LangSmith provider. - Allowed values: `braintrust`, `langsmith` - `provider_organization_id` (string, optional) — ProviderOrganizationID is the provider organization identifier. - `provider_project_id` (string, optional) — ProviderProjectID is the source project identifier. - `require_review` (boolean, optional) — RequireReview reports whether candidate review is required. - `revision` (integer, optional) — Revision is the import update revision. - `schedule` (v4.TraceImportSchedule, optional) — Schedule contains recurring import settings, when enabled. Example: \{"interval\_hours":4,"start\_from":"now","settle\_minutes":5,"max\_open\_hours":24}. - `selection` (v4.TraceImportSelection, optional) — Selection defines the source traces to import. Example: \{"trace\_ids":\["trace\_123"]}. - `source_cursor_updated_at` (string, optional) — SourceCursorUpdatedAt is the last source cursor update time. - `status` (string, optional) — Status is the import status. - `updated_at` (string, optional) — UpdatedAt is the last resource update time. - `uuid` (string, optional) — UUID is the trace import identifier. ### v4.TraceImportRun - `completed_at` (string, optional) — CompletedAt is the run completion time, when present. - `counts` (map from string to integer, optional) — Counts contains run totals by result type. - `created_at` (string, optional) — CreatedAt is the run creation time. - `due_at` (string, optional) — DueAt is the scheduled run time, when present. - `error_code` (string, optional) — ErrorCode is the safe run error code, when present. - `import_uuid` (string, optional) — ImportUUID is the owning import identifier. - `more_available` (boolean, optional) — MoreAvailable reports whether more matching traces remain. - `skip_reasons` (map from string to integer, optional) — SkipReasons contains skip totals by reason. - `started_at` (string, optional) — StartedAt is the run start time, when present. - `status` (string, optional) — Status is the run status. - `task_uuid` (string, optional) — TaskUUID is the Task identifier. - `trigger` (string, optional) — Trigger is the event that created the run. - `uuid` (string, optional) — UUID is the run identifier. ### v4.Task - `completed_at` (string, optional) — The time the task reached a terminal status; absent while it is still in progress. - `created_at` (string, optional) — The time the task was created. - `error` (v4.ErrorBody, optional) — The error that caused the task to fail; also present on a partial task when the worker can name a single cause. - `progress` (v4.TaskProgress, optional) — The last processing stage a worker reported for this task. It is not cleared when the task finishes, so a completed task may still show its final stage. - `result` (v4.TaskResult, optional) — Operation-specific output populated once the task reaches succeeded or partial, such as identifiers the operation could not return synchronously. - `started_at` (string, optional) — The time a worker began processing the task; absent until then. - `status` (enum, optional) — The task's current state: pending, processing, succeeded, partial, or failed. - Allowed values: `pending`, `processing`, `succeeded`, `partial`, `failed` - `type` (string, optional) — The kind of asynchronous operation the task represents. - `updated_at` (string, optional) — The time the task was last updated. - `uuid` (string, optional) — The unique identifier of the task, used to poll its status. ### v4.ErrorBody - `code` (string, optional) - `details` (map from string to any, optional) - `message` (string, optional) - `param` (string, optional) - `request_id` (string, optional) ### v4.TraceContentMapping - `include_system_messages` (boolean, optional) — IncludeSystemMessages controls whether system messages become events. - `metadata_keys` (list of string, optional) — MetadataKeys contains root metadata keys copied to the Trace. ### v4.ObjectiveMappingRule - `key` (string, optional) — Key is the root metadata key to read. - `source` (enum, optional) — Source selects the objective source. - Allowed values: `first_user_message`, `root_input`, `metadata` ### v4.OutcomeMappingRule - `failed_below` (double, optional) — FailedBelow is the optional score threshold for failure. - `key` (string, optional) — Key is the metadata key for a metadata rule. - `name` (string, optional) — Name is the score name for a score rule. - `rule` (enum, optional) — Rule is the outcome mapping rule type. - Allowed values: `score`, `metadata`, `error` - `succeeded_at_or_above` (double, optional) — SucceededAtOrAbove is the score threshold for success. - `values` (map from string to string, optional) — Values maps metadata strings to Trace outcomes. ### v4.TaskFamilyMappingRule - `fallback` (string, optional) — Fallback is used when the selected source has no value. - `key` (string, optional) — Key is the metadata key for metadata mapping. - `prefix` (string, optional) — Prefix is the tag prefix for tag mapping. - `source` (enum, optional) — Source selects the task family source. - Allowed values: `fixed`, `metadata`, `tag_prefix`, `name` - `value` (string, optional) — Value is the fixed task family value. ### v4.TraceFilter - `has_error` (boolean, optional) — HasError filters traces by their error state. - `metadata` (map from string to any, optional) — Metadata contains exact-match root metadata filters. Example: \{"team":"support"}. - `name` (string, optional) — Name is the exact trace name filter. - `scores` (list of v4.TraceScoreRange, optional) — Scores contains score name and range filters. Example: \[\{"name":"quality","min":0.5}]. - `started_after` (string, optional) — StartedAfter is the inclusive trace start-time lower bound. - `started_before` (string, optional) — StartedBefore is the exclusive trace start-time upper bound. - `tags_all` (list of string, optional) — TagsAll contains tags that every result must include. - `tags_any` (list of string, optional) — TagsAny contains tags that at least one result must include. ### v4.TraceImportRunReference - `completed_at` (string, optional) — CompletedAt is the run completion time, when present. - `started_at` (string, optional) — StartedAt is the run start time, when present. - `status` (enum, optional) — Status is the run status. - Allowed values: `pending`, `running`, `succeeded`, `partial`, `failed`, `canceled` - `trigger` (enum, optional) — Trigger is the event that created the run. - Allowed values: `create`, `schedule`, `manual` - `uuid` (string, optional) — UUID is the run identifier. ### v4.TaskProgress - `stage` (string, optional) — The most recent processing stage reported by the worker handling the task. ### v4.TaskResult - `content_policy` (v4.TaskResultContentPolicy, optional) — The content policy outcome of the task. - `edge_uuid` (string, optional) — The UUID of the edge that the task wrote. - `edges` (list of v4.TaskResultEdge, optional) — The edges that the task wrote. - `episode_uuid` (string, optional) — The UUID of the episode that the task added. - `episodes` (list of v4.TaskResultEpisode, optional) — The content policy outcome of each message that the task added. - `hyperedge_uuid` (string, optional) — The UUID of the hyperedge that the task created. - `skill_uuid` (string, optional) — The UUID of the skill that the task imported. - `source_node_uuid` (string, optional) — The UUID of the source node of the edge that the task wrote. - `target_node_uuid` (string, optional) — The UUID of the target node of the edge that the task wrote. ### v4.TraceScoreRange - `max` (double, optional) — Max is the inclusive score upper bound. - `min` (double, optional) — Min is the inclusive score lower bound. - `name` (string, optional) — Name is the provider score name. ### v4.TaskResultContentPolicy - `category_keys` (list of string, optional) — The keys of the categories with a matched rule. - `dropped_count` (integer, optional) — The number of derived candidates of the episode that were dropped. - `failed_count` (integer, optional) — The number of episodes in the batch whose evaluation failed. - `retained_count` (integer, optional) — The number of derived candidates of the episode that were published to the graph. - `revision` (integer, optional) — The project revision number of the policy that the graph bound. - `status` (enum, optional) — The evaluation status of the episode. pending means the evaluation has not finished, complete means every candidate was evaluated, and failed means ingestion retries were exhausted. - Allowed values: `pending`, `complete`, `failed` - `violated` (boolean, optional) — Whether at least one derived candidate of the episode matched a rule. - `violated_count` (integer, optional) — The number of episodes in the batch that a content policy flagged. ### v4.TaskResultEdge - `edge_uuid` (string, optional) — The UUID of the edge. - `source_node_uuid` (string, optional) — The UUID of the source node of the edge. - `target_node_uuid` (string, optional) — The UUID of the target node of the edge. ### v4.TaskResultEpisode - `content_policy` (v4.TaskResultContentPolicy, optional) — The content policy state of the episode. - `episode_uuid` (string, optional) — The UUID of the episode of the message. ## Examples ### Example 1 **Request** ```json {} ``` **Response** ```json { "import": { "agent_uuid": "f8b28f94-4f5a-4b3a-b782-87aa8464ac04", "connection_uuid": "8c78a85e-eac2-4f57-b5f5-59a68a1e77a1", "created_at": "2026-01-01T00:00:00Z", "imported_trace_count": 10, "last_run": { "completed_at": "2026-01-01T00:01:00Z", "started_at": "2026-01-01T00:00:01Z", "status": "succeeded", "trigger": "create", "uuid": "ea7e2724-9bfd-4ca1-aa5c-40a1dd72a688" }, "learn_from": true, "mapping": { "content": { "include_system_messages": false, "metadata_keys": [ "ticket_id", "queue" ] }, "include_outcomes": [ "succeeded", "failed" ], "objective": { "key": "objective", "source": "metadata" }, "outcome": [ { "failed_below": 0.4, "key": "outcome", "name": "quality", "rule": "score", "succeeded_at_or_above": 0.8, "values": { "ok": "succeeded" } } ], "score_verifier": false, "task_family": { "fallback": "support/general", "key": "task_family", "prefix": "task:", "source": "fixed", "value": "support/refund" } }, "name": "Support traces", "next_run_at": "2026-01-01T04:00:00Z", "on_source_change": "ignore", "pause_reason": "user", "provider": "braintrust", "provider_organization_id": "org_123", "provider_project_id": "project_123", "require_review": false, "revision": 1, "schedule": { "interval_hours": 4, "start_from": "now", "max_open_hours": 24, "settle_minutes": 60 }, "selection": { "filter": { "has_error": false, "metadata": {}, "name": "Handle support request", "scores": [ { "max": 1, "min": 0.5, "name": "quality" } ], "started_after": "2026-01-01T00:00:00Z", "started_before": "2026-02-01T00:00:00Z", "tags_all": [ "support", "prod" ], "tags_any": [ "support", "billing" ] }, "trace_ids": [ "trace_123", "trace_456" ] }, "source_cursor_updated_at": "2026-01-01T00:00:00Z", "status": "active", "updated_at": "2026-01-01T00:00:00Z", "uuid": "332c28e1-e6a7-4bca-97b2-ef1ec82c65fa" }, "run": { "completed_at": "2026-01-01T00:01:00Z", "counts": { "imported": 10 }, "created_at": "2026-01-01T00:00:00Z", "due_at": "2026-01-01T04:00:00Z", "error_code": "credential_rejected", "import_uuid": "332c28e1-e6a7-4bca-97b2-ef1ec82c65fa", "more_available": false, "skip_reasons": { "trace_not_closed": 1 }, "started_at": "2026-01-01T00:00:01Z", "status": "pending", "task_uuid": "3124c01a-8f49-4bfd-9758-6ce491a377c1", "trigger": "create", "uuid": "ea7e2724-9bfd-4ca1-aa5c-40a1dd72a688" }, "task": { "completed_at": "string", "created_at": "string", "error": { "code": "string", "details": {}, "message": "string", "param": "string", "request_id": "string" }, "progress": { "stage": "string" }, "result": { "content_policy": { "category_keys": [ "health" ], "dropped_count": 0, "failed_count": 1, "retained_count": 7, "revision": 3, "status": "complete", "violated": false, "violated_count": 2 }, "edge_uuid": "7a1f3c2e-4b5d-4e6f-8a9b-0c1d2e3f4a5b", "edges": [ { "edge_uuid": "7a1f3c2e-4b5d-4e6f-8a9b-0c1d2e3f4a5b", "source_node_uuid": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "target_node_uuid": "c3d4e5f6-a7b8-4c9d-8e1f-2a3b4c5d6e7f" } ], "episode_uuid": "f6a7b8c9-d0e1-4f2a-9b4c-5d6e7f8091a2", "episodes": [ { "content_policy": { "category_keys": [ "health" ], "dropped_count": 0, "failed_count": 1, "retained_count": 7, "revision": 3, "status": "complete", "violated": false, "violated_count": 2 }, "episode_uuid": "f6a7b8c9-d0e1-4f2a-9b4c-5d6e7f8091a2" } ], "hyperedge_uuid": "d4e5f6a7-b8c9-4d0e-9f2a-3b4c5d6e7f80", "skill_uuid": "e5f6a7b8-c9d0-4e1f-8a3b-4c5d6e7f8091", "source_node_uuid": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "target_node_uuid": "c3d4e5f6-a7b8-4c9d-8e1f-2a3b4c5d6e7f" }, "started_at": "string", "status": "pending", "type": "string", "updated_at": "string", "uuid": "string" } } ``` ### Example 2 **Request** ```json {} ``` **Response** ```json { "import": { "agent_uuid": "f8b28f94-4f5a-4b3a-b782-87aa8464ac04", "connection_uuid": "8c78a85e-eac2-4f57-b5f5-59a68a1e77a1", "created_at": "2026-01-01T00:00:00Z", "imported_trace_count": 10, "last_run": { "completed_at": "2026-01-01T00:01:00Z", "started_at": "2026-01-01T00:00:01Z", "status": "succeeded", "trigger": "create", "uuid": "ea7e2724-9bfd-4ca1-aa5c-40a1dd72a688" }, "learn_from": true, "mapping": { "content": { "include_system_messages": false, "metadata_keys": [ "ticket_id", "queue" ] }, "include_outcomes": [ "succeeded", "failed" ], "objective": { "key": "objective", "source": "metadata" }, "outcome": [ { "failed_below": 0.4, "key": "outcome", "name": "quality", "rule": "score", "succeeded_at_or_above": 0.8, "values": { "ok": "succeeded" } } ], "score_verifier": false, "task_family": { "fallback": "support/general", "key": "task_family", "prefix": "task:", "source": "fixed", "value": "support/refund" } }, "name": "Support traces", "next_run_at": "2026-01-01T04:00:00Z", "on_source_change": "ignore", "pause_reason": "user", "provider": "braintrust", "provider_organization_id": "org_123", "provider_project_id": "project_123", "require_review": false, "revision": 1, "schedule": { "interval_hours": 4, "start_from": "now", "max_open_hours": 24, "settle_minutes": 60 }, "selection": { "filter": { "has_error": false, "metadata": {}, "name": "Handle support request", "scores": [ { "max": 1, "min": 0.5, "name": "quality" } ], "started_after": "2026-01-01T00:00:00Z", "started_before": "2026-02-01T00:00:00Z", "tags_all": [ "support", "prod" ], "tags_any": [ "support", "billing" ] }, "trace_ids": [ "trace_123", "trace_456" ] }, "source_cursor_updated_at": "2026-01-01T00:00:00Z", "status": "active", "updated_at": "2026-01-01T00:00:00Z", "uuid": "332c28e1-e6a7-4bca-97b2-ef1ec82c65fa" }, "run": { "completed_at": "2026-01-01T00:01:00Z", "counts": { "imported": 10 }, "created_at": "2026-01-01T00:00:00Z", "due_at": "2026-01-01T04:00:00Z", "error_code": "credential_rejected", "import_uuid": "332c28e1-e6a7-4bca-97b2-ef1ec82c65fa", "more_available": false, "skip_reasons": { "trace_not_closed": 1 }, "started_at": "2026-01-01T00:00:01Z", "status": "pending", "task_uuid": "3124c01a-8f49-4bfd-9758-6ce491a377c1", "trigger": "create", "uuid": "ea7e2724-9bfd-4ca1-aa5c-40a1dd72a688" }, "task": { "completed_at": "string", "created_at": "string", "error": { "code": "string", "details": {}, "message": "string", "param": "string", "request_id": "string" }, "progress": { "stage": "string" }, "result": { "content_policy": { "category_keys": [ "health" ], "dropped_count": 0, "failed_count": 1, "retained_count": 7, "revision": 3, "status": "complete", "violated": false, "violated_count": 2 }, "edge_uuid": "7a1f3c2e-4b5d-4e6f-8a9b-0c1d2e3f4a5b", "edges": [ { "edge_uuid": "7a1f3c2e-4b5d-4e6f-8a9b-0c1d2e3f4a5b", "source_node_uuid": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "target_node_uuid": "c3d4e5f6-a7b8-4c9d-8e1f-2a3b4c5d6e7f" } ], "episode_uuid": "f6a7b8c9-d0e1-4f2a-9b4c-5d6e7f8091a2", "episodes": [ { "content_policy": { "category_keys": [ "health" ], "dropped_count": 0, "failed_count": 1, "retained_count": 7, "revision": 3, "status": "complete", "violated": false, "violated_count": 2 }, "episode_uuid": "f6a7b8c9-d0e1-4f2a-9b4c-5d6e7f8091a2" } ], "hyperedge_uuid": "d4e5f6a7-b8c9-4d0e-9f2a-3b4c5d6e7f80", "skill_uuid": "e5f6a7b8-c9d0-4e1f-8a3b-4c5d6e7f8091", "source_node_uuid": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "target_node_uuid": "c3d4e5f6-a7b8-4c9d-8e1f-2a3b4c5d6e7f" }, "started_at": "string", "status": "pending", "type": "string", "updated_at": "string", "uuid": "string" } } ```