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

# Quickstart

> Install the SDK and export your first trajectories in under 5 minutes.

## Prerequisites

* Python 3.11 or higher
* A [LangSmith API key](https://smith.langchain.com/) (starts with `lsv2_pt_...`)
* A LangSmith project with existing traces

## Installation

<CodeGroup>
  ```bash pip theme={null}
  pip install trajectory-sdk
  ```

  ```bash uv theme={null}
  uv add trajectory-sdk
  ```
</CodeGroup>

## Configure the SDK

Initialize the SDK with your LangSmith credentials and (optionally) a Trajectory API key for uploading:

```python theme={null}
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](/sdk/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](/sdk/pii-redaction))                                        |
| `debug`              | No       | Enable debug logging                                                                                                        |

## Individual Import

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

```python theme={null}
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:

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

## Bulk Import

Import all conversations from a project at once:

```python theme={null}
trajectories = tj.import_conversations(bulk=True)
```

You can also scope the export to a time window:

```python theme={null}
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](/sdk/bulk-import) for details and how to find your workspace ID.

## Upload

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

```python theme={null}
tj.upload(trajectories, dataset="my_dataset")
```

<Note>
  `trajectory_api_key` must be set in `tj.init()` (or via the `TRAJECTORY_API_KEY` env var) for upload to work.
</Note>

## Save to Disk

If you prefer to save locally instead of uploading:

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

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="lightbulb" href="/concepts">
    Learn what Trajectories, Steps, and Messages represent.
  </Card>

  <Card title="Bulk Export" icon="layer-group" href="/sdk/bulk-import">
    Export all conversations from a project at once.
  </Card>

  <Card title="Bring Your Own Data" icon="file-import" href="/sdk/bring-your-own-data">
    Build trajectories without a provider — from CSV, JSONL, OpenAI, Anthropic, etc.
  </Card>

  <Card title="Telemetry Events" icon="signal-stream" href="/sdk/telemetry-events">
    Push product telemetry from your app into Trajectory.
  </Card>

  <Card title="Linking Events to Trajectories" icon="link" href="/sdk/linking-events-to-trajectories">
    Correlate uploaded trajectories with telemetry via `trace_id`.
  </Card>

  <Card title="API Reference" icon="square-terminal" href="/sdk/api-reference">
    Full function signatures and parameters.
  </Card>
</CardGroup>