Quickstart

Prerequisites

Python 3.11 or higher
A LangSmith API key (starts with lsv2_pt_...)
A LangSmith project with existing traces

Installation

pip install trajectory-sdk

uv add trajectory-sdk

Configure the SDK

Initialize the import SDK with your LangSmith credentials. Uploads use a separate generated Client, which reads TRAJECTORY_API_KEY from the environment by default:

import trajectory_sdk as tj

tj.init(
    provider="langsmith",
    project_id="your-project-id",
    workspace_id="your-workspace-id",
    api_key="lsv2_pt_...",                  # or set LANGSMITH_API_KEY env var
)

from trajectory import Client

client = Client()  # or Client(api_key="your-trajectory-api-key")

Parameter	Required	Description
`project_id`	Yes	Your project ID
`provider`	No	Trace provider (e.g. `"langsmith"`). Omit for telemetry-only or bring-your-own-data usage
`workspace_id`	No	LangSmith workspace UUID (required for bulk export)
`destination_id`	No	Bulk export destination UUID (required for live bulk export)
`api_key`	No	Provider API key. Reads from `LANGSMITH_API_KEY` / `LANGCHAIN_API_KEY` env var if omitted
`transforms`	No	List of transforms applied after building (e.g. PII redaction)

Individual Import

List conversations, pick the ones you want, and import them:

conversations = tj.list_conversations(limit=5)
ids = [c.conversation_id for c in conversations]
trajectories = tj.import_conversations(ids)

This fetches the full run tree for each conversation, extracts messages, and builds Trajectory objects. You can also pass IDs directly if you already know which conversations you want:

trajectories = tj.import_conversations(["cc_abc123", "cc_def456"])

Bulk Import

Import all conversations from a project at once:

trajectories = tj.import_conversations(bulk=True)

You can also scope the export to a time window:

from datetime import timedelta

trajectories = tj.import_conversations(bulk=True, since=timedelta(hours=1))

Bulk import discovers conversations in your project, triggers a LangSmith export, and parses the result. See Bulk Export for details and how to find your workspace ID.

Upload

After importing (either way), upload trajectories to the Trajectory platform:

from trajectory.lib import upload_trajectories

result = upload_trajectories(client, trajectories, dataset="my_dataset")
print(result.uploaded, result.skipped)

Client() reads TRAJECTORY_API_KEY and TRAJECTORY_BASE_URL from the environment. Pass api_key or base_url to the client explicitly to override either value.

Save to Disk

If you prefer to save locally instead of uploading:

tj.save(trajectories, "./exports")

Each Trajectory is written as a JSON file named by conversation ID.

Next Steps

Core Concepts

Learn what Trajectories, Steps, and Messages represent.

Bulk Export

Export all conversations from a project at once.

Bring Your Own Data

Build trajectories without a provider — from CSV, JSONL, OpenAI, Anthropic, etc.

Telemetry Events

Push product telemetry from your app into Trajectory.

Linking Events to Trajectories

Correlate uploaded trajectories with telemetry via trace_id.

API Reference

Full function signatures and parameters.

Getting Started

SDK

HTTP API

Platform

Prerequisites

Installation

Configure the SDK

Individual Import

Bulk Import

Upload

Save to Disk

Next Steps

Core Concepts

Bulk Export

Bring Your Own Data

Telemetry Events

Linking Events to Trajectories

API Reference

​Prerequisites

​Installation

​Configure the SDK

​Individual Import

​Bulk Import

​Upload

​Save to Disk

​Next Steps

Core Concepts

Bulk Export

Bring Your Own Data

Telemetry Events

Linking Events to Trajectories

API Reference

Prerequisites

Installation

Configure the SDK

Individual Import

Bulk Import

Upload

Save to Disk

Next Steps