> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trajectory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Import Traces

> Standard workflow: connect to a provider, list conversations, and import them as Trajectories.

## Prerequisites

* `pip install trajectory-sdk`
* A [LangSmith API key](https://smith.langchain.com/) (starts with `lsv2_pt_...`)
* A LangSmith project ID with existing traces

## Walkthrough

```python theme={null}
import trajectory_sdk as tj

# 1. Initialize
tj.init(
    provider="langsmith",
    api_key="lsv2_pt_...",
    project_id="your-project-id",
    trajectory_api_key="your-trajectory-api-key",  # required for upload
)

# 2. List conversations
conversations = tj.list_conversations(limit=5)

# 3. Extract IDs and import as Trajectories
ids = [c.conversation_id for c in conversations]
trajectories = tj.import_conversations(ids)

# 4. Upload to the Trajectory platform
tj.upload(trajectories, dataset="my-dataset-v1")
```

You can also save to disk instead of (or in addition to) uploading:

```python theme={null}
tj.save(trajectories, "./exports")
```

Each conversation becomes one JSON file in `./exports/`, named by conversation ID.

## Import by ID

If you already know which conversations you want:

```python theme={null}
trajectories = tj.import_conversations([
    "cc_abc123",
    "cc_def456",
])
```

## LangSmith Notes

* Conversations are identified by `conversation_id` or `session_id` in run metadata. Runs without either are treated as standalone conversations.
* Roles are normalized: `human` → `user`, `ai` → `assistant`.
* API responses are cached in-memory for 5 minutes to reduce load on repeated imports.