API Reference

Functions

`tj.init()`

Configure the SDK. Call once before other functions.

tj.init(
    *,
    provider: str = "langsmith",
    api_key: str | None = None,
    project_id: str,
    workspace_id: str | None = None,
    destination_id: str | None = None,
    trajectory_api_key: str | None = None,
    transforms: list[BaseTransform] | None = None,
    debug: bool = False,
) -> None

Parameter	Type	Default	Description
`provider`	`str`	`"langsmith"`	Trace provider to connect to
`api_key`	`str \| None`	`None`	Provider API key. If omitted, reads from `LANGSMITH_API_KEY` or `LANGCHAIN_API_KEY` environment variable.
`project_id`	`str`	required	Provider project/session ID
`workspace_id`	`str \| None`	`None`	LangSmith workspace/tenant ID. Required for bulk export.
`destination_id`	`str \| None`	`None`	Bulk export destination ID. Required for bulk export.
`trajectory_api_key`	`str \| None`	`None`	API key for uploading trajectories. Can also be set via `TRAJECTORY_API_KEY` environment variable.
`transforms`	`list[BaseTransform] \| None`	`None`	List of transforms to apply after building (e.g. PII redaction)
`debug`	`bool`	`False`	Enable debug logging

`tj.list_conversations()`

List available conversations from the configured provider.

tj.list_conversations(*, limit: int = 50) -> list[ConversationSummary]

Parameter	Type	Default	Description
`limit`	`int`	`50`	Max conversations to return

Returns a list of ConversationSummary:

Field	Type	Description
`conversation_id`	`str`	Unique conversation identifier
`num_turns`	`int`	Number of turns
`first_seen`	`str \| None`	ISO timestamp of earliest trace
`last_seen`	`str \| None`	ISO timestamp of most recent trace
`root_run_names`	`list[str]`	Names of top-level runs

`tj.import_conversations()`

Import conversations and return one Trajectory per conversation.

tj.import_conversations(
    conversations: list[str] | list[ConversationSummary] | None = None,
    *,
    bulk: bool = False,
    source: str | None = None,
    limit: int | None = None,
    since: timedelta | datetime | None = None,
) -> list[Trajectory]

Parameter	Type	Default	Description
`conversations`	`list`	`None`	Conversation IDs or `ConversationSummary` objects
`bulk`	`bool`	`False`	Use bulk export path instead of individual API calls
`source`	`str \| None`	`None`	Path to a local parquet file. When `bulk=True` and `source` is omitted, the SDK triggers a live export from LangSmith (requires `workspace_id` and `destination_id` in `init()`).
`limit`	`int \| None`	`None`	Max conversations to process (bulk mode only)
`since`	`timedelta \| datetime \| None`	`None`	Time window for bulk export. Pass a `timedelta` (e.g. `timedelta(hours=1)`) to export recent data, or a `datetime` for an absolute start time. Only used when `bulk=True`.

`tj.save()`

Save Trajectories to JSON files on disk.

tj.save(
    trajectories: Trajectory | list[Trajectory],
    output_dir: str,
) -> None

Each Trajectory is saved as {output_dir}/{conversation_id}.json.

`tj.transform()`

Transform raw conversation data into a Trajectory without fetching from a provider. Useful for custom pipelines where you already have the raw data.

tj.transform(
    raw_data: dict,
    *,
    provider: str = "langsmith",
    api_key: str = "",
    project_id: str = "",
) -> Trajectory

Parameter	Type	Default	Description
`raw_data`	`dict`	required	Raw conversation data in the provider’s format
`provider`	`str`	`"langsmith"`	Provider to use for parsing
`api_key`	`str`	`""`	Provider API key (not needed for parsing)
`project_id`	`str`	`""`	Provider project ID (not needed for parsing)

`tj.upload()`

Upload trajectories to the Trajectory platform via the Trajectory API. Requires trajectory_api_key to be set in tj.init() or via the TRAJECTORY_API_KEY environment variable.

tj.upload(
    trajectories: Trajectory | list[Trajectory],
    dataset: str,
) -> None

Parameter	Type	Description
`trajectories`	`Trajectory \| list[Trajectory]`	Trajectories to upload
`dataset`	`str`	Dataset name to group the uploaded trajectories

Empty trajectories (0 steps) are automatically skipped.

Data Models

All models are frozen dataclasses (immutable after construction).

Trajectory

Field	Type	Description
`task`	`Task`	Conversation metadata
`steps`	`list[Step]`	Ordered decision points with cumulative messages
`reward`	`Reward \| None`	Aggregate reward signal
`metrics`	`TrajectoryMetrics \| None`	Computed content metrics
`execution_metrics`	`ExecutionMetrics \| None`	Timing data
`reference_trajectory`	`dict \| None`	Optional reference trajectory for comparison
`telemetry`	`Telemetry \| None`	Source telemetry metadata
`idx`	`int \| None`	Index within a batch
`error`	`str \| None`	Error if conversation failed

Task

Field	Type	Description
`id`	`str \| None`	Task identifier
`data_source`	`str \| None`	Provider name (e.g. `"langsmith"`)
`conversation_id`	`str \| None`	Unique conversation identifier
`num_turns`	`int \| None`	Number of user-agent turns
`num_steps`	`int \| None`	Number of steps
`total_tokens`	`int \| None`	Total tokens consumed
`total_cost`	`float \| None`	Estimated cost in USD

Step

Field	Type	Description
`messages`	`list[Message]`	Cumulative messages up to this point
`reward`	`Reward \| None`	Per-step reward signal
`info`	`dict \| None`	Provider-specific metadata
`trainable_status`	`TrainableStatus`	Training suitability flag

Message

Field	Type	Description
`role`	`Role`	`"system"`, `"user"`, `"assistant"`, or `"tool"`
`content`	`str \| None`	Text content (None for tool-call-only messages)
`tool_calls`	`list[ToolCall] \| None`	Tool invocations by the assistant
`tool_response`	`ToolResponse \| None`	Tool execution result
`tool_definitions`	`list[ToolDefinition] \| None`	Tool definitions available to the model at this point
`usage`	`dict \| None`	Token usage stats
`finish_reason`	`str \| None`	Why the model stopped (`"stop"`, `"tool_calls"`)
`metadata`	`dict \| None`	Provider-specific message metadata
`reasoning`	`str \| None`	Chain-of-thought content
`trainable_status`	`TrainableStatus`	Training suitability flag

ToolCall

Field	Type	Description
`name`	`str`	Tool name
`arguments`	`dict`	Arguments passed to the tool
`id`	`str \| None`	Identifier matching the ToolResponse

ToolResponse

Field	Type	Description
`id`	`str`	Matches the ToolCall `id`
`name`	`str`	Tool name
`arguments`	`dict`	Arguments that were passed
`response`	`Any \| None`	Return value
`error`	`str \| None`	Error if the call failed
`metadata`	`dict \| None`	Provider-specific metadata

ToolDefinition

Field	Type	Description
`name`	`str`	Tool name
`description`	`str`	What the tool does
`parameters`	`dict`	JSON Schema for tool arguments

Telemetry

Field	Type	Description
`source`	`str`	Telemetry source identifier
`data`	`dict`	Raw telemetry data

TrajectoryMetrics & ExecutionMetrics

Field	Type	Description
`steps`	`int \| None`	Total steps
`tokens_generated`	`int \| None`	Total completion tokens
`aggregated_reward`	`float \| None`	Aggregate reward value
`num_tool_calls`	`int \| None`	Total tool invocations
`num_tool_failures`	`int \| None`	Failed tool calls
`num_tool_response_none`	`int \| None`	Tool calls with no response
`tool_error_rate`	`float \| None`	Failure ratio
`env_time`	`float \| None`	Time in tool execution (seconds)
`llm_time`	`float \| None`	Time waiting for LLM (seconds)
`total_time`	`float \| None`	Wall-clock time (seconds)
`termination_reason`	`TerminationReason \| None`	Why the conversation ended

Type Aliases

Role = Literal["system", "user", "assistant", "tool"]

TerminationReason = Literal[
    "TIMEOUT", "ENV_DONE", "MAX_STEPS", "TRUNCATION", "STALE", "ERROR", "NONE"
]

Getting Started

SDK

Platform

Functions

`tj.init()`

`tj.list_conversations()`

`tj.import_conversations()`

`tj.save()`

`tj.transform()`

`tj.upload()`

Data Models

Trajectory

Task

Step

Message

ToolCall

ToolResponse

ToolDefinition

Telemetry

TrajectoryMetrics & ExecutionMetrics

Type Aliases

Getting Started

SDK

Platform

​Functions

​tj.init()

​tj.list_conversations()

​tj.import_conversations()

​tj.save()

​tj.transform()

​tj.upload()

​Data Models

​Trajectory

​Task

​Step

​Message

​ToolCall

​ToolResponse

​ToolDefinition

​Telemetry

​TrajectoryMetrics & ExecutionMetrics

​Type Aliases

Functions

`tj.init()`

`tj.list_conversations()`

`tj.import_conversations()`

`tj.save()`

`tj.transform()`

`tj.upload()`

Data Models

Trajectory

Task

Step

Message

ToolCall

ToolResponse

ToolDefinition

Telemetry

TrajectoryMetrics & ExecutionMetrics

Type Aliases