> 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 trajectory imports

GET https://api.getzep.com/api/v4/agents/{agent_uuid}/trajectory-imports

List trajectory imports that belong to this Agent.

Reference: https://docs-beta.getzep.com/sdk-reference/agent/trajectory-import/list

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

### Query parameters

- `limit` (integer, optional) — Page size
- `cursor` (string, optional) — Opaque page cursor

## Response

### 200

OK

- `items` (list of v4.TrajectoryImport, optional) — Items contains trajectory imports on this page. Example: \[\{"uuid":"332c28e1-e6a7-4bca-97b2-ef1ec82c65fa","name":"Support traces"}].
- `next_cursor` (string, optional) — NextCursor is the cursor for the next page.
- `total_size` (integer, optional) — TotalSize is the number of matching imports.

## Errors

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

## Types

### v4.TrajectoryImport

- `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_trajectory_count` (integer, optional) — ImportedTrajectoryCount is the number of Trajectories currently owned by this import.
- `last_run` (v4.TrajectoryImportRunReference, 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.TrajectoryMapping, optional) — Mapping defines how traces become Trajectories. 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` (string, optional) — OnSourceChange defines how changed source traces are handled.
- `pause_reason` (enum, optional) — PauseReason is the reason for a paused import, when present.
  - Allowed values: `user`, `credential_rejected`, `provider_project_not_found`
- `provider` (string, optional) — Provider is the observability provider.
- `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.TrajectoryImportSchedule, optional) — Schedule contains recurring import settings, when enabled. Example: \{"interval\_hours":4,"start\_from":"24h","settle\_minutes":5,"max\_open\_hours":24}.
- `selection` (v4.TrajectoryImportSelection, 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 trajectory import identifier.

### v4.ErrorBody

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

### v4.TrajectoryImportRunReference

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

- `interval_hours` (integer, optional) — IntervalHours is the scheduled run interval.
- `max_open_hours` (integer, optional) — MaxOpenHours is the maximum wait for an open trace.
- `settle_minutes` (integer, optional) — SettleMinutes is the wait time for trace updates.
- `start_from` (string, optional) — StartFrom selects the initial history window.

### v4.TrajectoryImportSelection

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

## Examples

**Response**

```json
{
  "items": [
    {
      "agent_uuid": "f8b28f94-4f5a-4b3a-b782-87aa8464ac04",
      "connection_uuid": "8c78a85e-eac2-4f57-b5f5-59a68a1e77a1",
      "created_at": "2026-01-01T00:00:00Z",
      "imported_trajectory_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,
        "max_open_hours": 24,
        "settle_minutes": 5,
        "start_from": "24h"
      },
      "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"
    }
  ],
  "next_cursor": "eyJvZmZzZXQiOjI1fQ",
  "total_size": 1
}
```