Create a trace import | Zep Documentation

{
  "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"
  }
}

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

Authentication

AuthorizationApi-Key

Type “Api-Key” followed by a space and the project API key.

Path parameters

agent_uuidstringRequired

Agent UUID

Request

Import request

connection_uuidstringOptional

ConnectionUUID identifies the project trace connection.

learn_frombooleanOptional

LearnFrom controls whether imported evidence can support Skills.

mappingobjectOptional

Mapping defines how source traces become Traces. Example: {“task_family”:{“source”:“fixed”,“value”:“support”}}.

namestringOptional

Name is the import display name.

on_source_changeenumOptional

OnSourceChange defines how changed source traces are handled.

Allowed values:

provider_project_idstringOptional

ProviderProjectID is the source provider project identifier.

require_reviewbooleanOptional

RequireReview requires review for candidates backed by this import.

scheduleobjectOptional

Schedule enables recurring imports when supplied. Example: {“interval_hours”:4,“start_from”:“now”,“settle_minutes”:5,“max_open_hours”:24}.

selectionobjectOptional

Selection defines the traces to import. Example: {“trace_ids”:[“trace_123”]}.

Response

Created

importobjectOptional

Import is the created import resource. Example: {“uuid”:“332c28e1-e6a7-4bca-97b2-ef1ec82c65fa”}.

runobjectOptional

Run is the pending one-time run. The field is absent for a scheduled import. Example: {“uuid”:“ea7e2724-9bfd-4ca1-aa5c-40a1dd72a688”,“status”:“pending”}.

taskobjectOptional

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

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error