> 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 source traces

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

Filter provider traces. Example body: `{"provider_project_id":"project_123","filter":{"started_after":"2026-01-01T00:00:00Z"}}`.

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

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

### Query parameters

- `limit` (integer, optional) — Page size from 1 to 100; default 25
- `cursor` (string, optional) — Opaque page cursor

### Body (application/json)

This endpoint expects a v4.SourceTraceListRequest.

- `provider_project_id` (string, required) — ProviderProjectID is the provider project identifier.
- `filter` (v4.TraceFilter, optional) — Filter contains provider trace filters. Example: \{"started\_after":"2026-01-01T00:00:00Z"}.

## Response

### 200

OK

- `items` (list of v4.SourceTraceSummary, optional) — Items contains the source trace summaries on this page. Example: \[\{"trace\_id":"trace\_123","name":"Support trace"}].
- `next_cursor` (string, optional) — NextCursor is the cursor for the next provider page.

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

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

## Examples

**Request**

```json
{
  "provider_project_id": "project_123"
}
```

**Response**

```json
{
  "items": [
    {
      "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,
      "started_at": "2026-01-01T00:00:00Z",
      "tags": [
        "support",
        "prod"
      ],
      "trace_id": "trace_123"
    }
  ],
  "next_cursor": "page-2"
}
```