Skip to main content

​
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

​
Configure the SDK

Initialize the SDK with your LangSmith credentials and (optionally) a Trajectory API key for uploading: 
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
    trajectory_api_key="your-trajectory-api-key",  # or set TRAJECTORY_API_KEY env var
)
ParameterRequiredDescription
project_idYesYour project ID
providerNoTrace provider (e.g. "langsmith"). Omit for telemetry-only or bring-your-own-data usage
workspace_idNoLangSmith workspace UUID (required for bulk export)
destination_idNoBulk export destination UUID (required for live bulk export)
api_keyNoProvider API key. Reads from LANGSMITH_API_KEY / LANGCHAIN_API_KEY env var if omitted
trajectory_api_keyNoRequired for tj.upload(), tj.upload_trace(), and tj.push_events(). Reads from TRAJECTORY_API_KEY env var if omitted
transformsNoList of transforms applied after building (e.g. PII redaction)
debugNoEnable debug logging

​
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: 
tj.upload(trajectories, dataset="my_dataset")
trajectory_api_key must be set in tj.init() (or via the TRAJECTORY_API_KEY env var) for upload to work.

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