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

# Create a trajectory import

POST https://api.getzep.com/api/v4/agents/{agent_uuid}/trajectory-imports
Content-Type: application/json

Create a scheduled import or queue a one-time import. 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"}}}`.

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

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

### Body (application/json)

This endpoint expects a v4.CreateTrajectoryImportRequest.

- `connection_uuid` (string, optional) — ConnectionUUID identifies the project trace connection.
- `learn_from` (boolean, optional) — LearnFrom controls whether imported evidence can support Skills.
- `mapping` (v4.TrajectoryMapping, optional) — Mapping defines how source traces become Trajectories. Example: \{"task\_family":\{"source":"fixed","value":"support"}}.
- `name` (string, optional) — Name is the import display name.
- `on_source_change` (string, optional) — OnSourceChange defines how changed source traces are handled.
- `provider_project_id` (string, optional) — ProviderProjectID is the source provider project identifier.
- `require_review` (boolean, optional) — RequireReview requires review for candidates backed by this import.
- `schedule` (v4.TrajectoryImportSchedule, optional) — Schedule enables recurring imports when supplied. Example: \{"interval\_hours":4,"start\_from":"24h","settle\_minutes":5,"max\_open\_hours":24}.
- `selection` (v4.TrajectoryImportSelection, optional) — Selection defines the traces to import. Example: \{"trace\_ids":\["trace\_123"]}.

## Response

### 201

Created

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

### 202

Accepted

- `any`

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

### 409 Conflict Error

Conflict

- `error` (v4.ErrorBody, optional)

### 422 Unprocessable Entity Error

Unprocessable Entity

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

### Example 1

**Request**

```json
{}
```

**Response**

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

### Example 2

**Request**

```json
{}
```

**Response**

```json
{
  "import": {
    "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"
  },
  "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": {},
    "started_at": "string",
    "status": "string",
    "type": "string",
    "updated_at": "string",
    "uuid": "string"
  }
}
```