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

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
`trajectory_api_key`	No	Required for `tj.upload()`, `tj.upload_trace()`, and `tj.push_events()`. Reads from `TRAJECTORY_API_KEY` env var if omitted
`transforms`	No	List of transforms applied after building (e.g. PII redaction)
`debug`	No	Enable 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.

Getting Started

SDK

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