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

# Get a source trace

POST https://api.getzep.com/api/v4/trace-connections/{connection_uuid}/traces/get
Content-Type: application/json

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

Reference: https://docs-beta.getzep.com/sdk-reference/trace-connection/trace/get

## Authentication

- `Authorization` header (required) (prefixed with ` Api-Key  `) — Type "Api-Key" followed by a space and the project API key.

## Request

### Path parameters

- `connection_uuid` (string, required) — Trace connection UUID

### Body (application/json)

This endpoint expects a v4.SourceTraceGetRequest.

- `provider_project_id` (string, required) — ProviderProjectID is the provider project identifier.
- `trace_id` (string, required) — TraceID is the provider trace identifier.
- `mapping` (v4.TrajectoryMapping, optional) — Mapping is an optional mapping preview configuration. Example: \{"task\_family":\{"source":"fixed","value":"support"}}.

## Response

### 200

OK

- `preview` (v4.TracePreview, optional) — Preview contains the optional mapping preview. Example: \{"event\_count":4}.
- `trace` (v4.SourceTrace, optional) — Trace is the requested provider trace. Example: \{"trace\_id":"trace\_123","spans":\[]}.

## 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)

### 502 Bad Gateway Error

Bad Gateway

- `error` (v4.ErrorBody, optional)

## Types

### v4.TrajectoryMapping

- `content` (v4.TrajectoryContentMapping, 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 Trajectory 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.TracePreview

- `event_count` (integer, optional) — EventCount is the number of mapped events.
- `mapping_result` (v4.TrajectoryMappingResult, optional) — MappingResult contains the resolved Trajectory fields. Example: \{"task\_family":"support","objective":"Help the customer"}.
- `skip_reason` (string, optional) — SkipReason is the reason the trace cannot be imported, when present.

### v4.SourceTrace

- `closed` (boolean, optional) — Closed reports whether the root span has ended.
- `ended_at` (string, optional) — EndedAt is the trace end time, when present.
- `has_error` (boolean, optional) — HasError reports whether the trace contains an error.
- `imported_trajectories` (list of v4.ImportedTrajectoryReference, optional) — ImportedTrajectories contains visible Zep Trajectories imported from this trace. Example: \[\{"agent\_uuid":"f8b28f94-4f5a-4b3a-b782-87aa8464ac04","trajectory\_uuid":"6a906e70-50ca-4e43-a874-5fcae02a71fa","import\_uuid":"332c28e1-e6a7-4bca-97b2-ef1ec82c65fa"}].
- `last_activity_at` (string, optional) — LastActivityAt is the most recent activity time across spans.
- `metadata` (map from string to any, optional) — Metadata contains the root span metadata summary. Example: \{"team":"support"}.
- `name` (string, optional) — Name is the trace name, when present.
- `scores` (map from string to double, optional) — Scores contains the trace score values.
- `source_revision` (string, optional) — SourceRevision is the provider revision for the trace.
- `source_url` (string, optional) — SourceURL is the provider link, when available.
- `span_count` (integer, optional) — SpanCount is the number of spans in the trace.
- `spans` (list of v4.SourceSpan, optional) — Spans contains the trace spans. Example: \[\{"span\_id":"span\_123","kind":"llm","name":"assistant\_response"}].
- `started_at` (string, optional) — StartedAt is the trace start time, when present.
- `tags` (list of string, optional) — Tags contains the trace tags.
- `trace_id` (string, optional) — TraceID is the provider trace identifier.

### v4.ErrorBody

- `code` (string, optional)
- `details` (map from string to any, optional)
- `message` (string, optional)
- `param` (string, optional)
- `request_id` (string, optional)

### v4.TrajectoryContentMapping

- `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 Trajectory.

### 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 Trajectory 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.TrajectoryMappingResult

- `metadata` (map from string to any, optional) — Metadata contains mapped source metadata. Example: \{"ticket\_id":"123"}.
- `objective` (string, optional) — Objective is the resolved objective.
- `outcome` (enum, optional) — Outcome is the resolved outcome.
  - Allowed values: `succeeded`, `failed`, `partial`, `abandoned`, `unknown`
- `outcome_rule` (enum, optional) — OutcomeRule is the rule that selected the outcome.
  - Allowed values: `score`, `metadata`, `error`
- `scores` (map from string to double, optional) — Scores contains provider score values.
- `task_family` (string, optional) — TaskFamily is the resolved task family.
- `verification` (string, optional) — Verification is the resolved verification state.

### v4.ImportedTrajectoryReference

- `agent_uuid` (string, optional) — AgentUUID is the visible Agent identifier.
- `import_uuid` (string, optional) — ImportUUID is the active import owner identifier.
- `trajectory_uuid` (string, optional) — TrajectoryUUID is the imported Trajectory identifier.

### v4.SourceSpan

- `created_at` (string, optional) — CreatedAt is the span creation time.
- `ended_at` (string, optional) — EndedAt is the span end time, when present.
- `error` (string, optional) — Error is the span error text, when present.
- `input` (V4SourceSpanInput, optional) — Input is the provider span input. Example: \{"messages":\[]}.
- `kind` (string, optional) — Kind is the normalized span kind.
- `metadata` (map from string to any, optional) — Metadata contains provider span metadata. Example: \{"team":"support"}.
- `model` (string, optional) — Model is the model identifier, when present.
- `name` (string, optional) — Name is the provider span name.
- `output` (V4SourceSpanOutput, optional) — Output is the provider span output. Example: \{"text":"Hello"}.
- `parent_span_id` (string, optional) — ParentSpanID is the parent span identifier, when present.
- `span_id` (string, optional) — SpanID is the provider span identifier.
- `started_at` (string, optional) — StartedAt is the span start time, when present.
- `tool_name` (string, optional) — ToolName is the tool name, when present.

### V4SourceSpanInput

Input is the provider span input. Example: \{"messages":\[]}.

### V4SourceSpanOutput

Output is the provider span output. Example: \{"text":"Hello"}.

## Examples

**Request**

```json
{
  "provider_project_id": "project_123",
  "trace_id": "trace_123"
}
```

**Response**

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