Get a source trace

POST

https://api.getzep.com/api/v4/trace-connections/:connection_uuid/traces/get

POST

/api/v4/trace-connections/:connection_uuid/traces/get

from zep_cloud import Zep
client = Zep(
    api_key="YOUR_API_KEY_HERE",
)
client.trace_connection.trace.get(
    connection_uuid="connection_uuid",
    provider_project_id="project_123",
    trace_id="trace_123",
)

{
  "preview": {
    "event_count": 4,
    "mapping_result": {
      "metadata": {},
      "objective": "Help the customer receive a refund",
      "outcome": "succeeded",
      "outcome_rule": "score",
      "scores": {
        "quality": 0.9
      },
      "task_family": "support/refund",
      "verification": "external"
    },
    "skip_reason": "trace_not_closed"
  },
  "trace": {
    "closed": true,
    "ended_at": "2026-01-01T00:01:00Z",
    "has_error": false,
    "imported_trajectories": [
      {
        "agent_uuid": "f8b28f94-4f5a-4b3a-b782-87aa8464ac04",
        "import_uuid": "332c28e1-e6a7-4bca-97b2-ef1ec82c65fa",
        "trajectory_uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa"
      }
    ],
    "last_activity_at": "2026-01-01T00:01:00Z",
    "metadata": {},
    "name": "Handle support request",
    "scores": {
      "quality": 0.9
    },
    "source_revision": "123456789",
    "source_url": "https://app.braintrust.dev/app/trace_123",
    "span_count": 4,
    "spans": [
      {
        "created_at": "2026-01-01T00:00:00Z",
        "ended_at": "2026-01-01T00:00:01Z",
        "error": "provider request failed",
        "input": {},
        "kind": "llm",
        "metadata": {},
        "model": "gpt-4o",
        "name": "assistant_response",
        "output": {},
        "parent_span_id": "span_parent",
        "span_id": "span_123",
        "started_at": "2026-01-01T00:00:00Z",
        "tool_name": "search"
      }
    ],
    "started_at": "2026-01-01T00:00:00Z",
    "tags": [
      "support",
      "prod"
    ],
    "trace_id": "trace_123"
  }
}

Read one trace and optionally preview a mapping. Example body: {"provider_project_id":"project_123","trace_id":"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

connection_uuidstringRequired

Trace connection UUID

Request

Trace ID and optional mapping

provider_project_idstringRequired

ProviderProjectID is the provider project identifier.

trace_idstringRequired

TraceID is the provider trace identifier.

mappingobjectOptional

Mapping is an optional mapping preview configuration. Example: {"task_family":{"source":"fixed","value":"support"}}.

Response

previewobjectOptional

Preview contains the optional mapping preview. Example: {"event_count":4}.

traceobjectOptional

Trace is the requested provider trace. Example: {"trace_id":"trace_123","spans":[]}.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

502

Bad Gateway Error