or run

tessl search

tessl/npm-langsmith

tessl install tessl/npm-langsmith@0.4.3

TypeScript client SDK for the LangSmith LLM tracing, evaluation, and monitoring platform.

API Reference

Complete API documentation for programmatic access to LangSmith.

Overview

The LangSmith API provides comprehensive programmatic access to all platform features. This section documents the Client class, type definitions, and all available methods.

Quick Navigation

Core Client

Client Overview - Start here for API overview
Client Construction - Setup and configuration
Utilities - Helper functions (uuid7, cache, etc.)

Resource Management

Projects - Project/session operations
Runs - Run creation and querying
Datasets - Dataset management
Examples - Example operations
Feedback - Feedback collection
Prompts - Prompt hub operations

Type Reference

Schemas - Complete TypeScript types

Method Selection Guide

Quick reference for choosing between similar methods.

Creating Examples

Method	Signature	Use When	Best For
`createExample()`	`(example: ExampleCreate)`	Single example creation	Individual examples, source run conversion
`createExamples()` (arrays)	`({ inputs: [], outputs: [] })`	Bulk with uniform structure	CSV import, parallel arrays, simple bulk data
`createExamples()` (objects)	`({ examples: [{...}] })`	Bulk with per-item config	Varied metadata, explicit per-example settings
`createLLMExample()`	`(input: string, output: string, options)`	Text completion datasets	LLM-format data, simple text in/out
`createChatExample()`	`(messages: [], response: [], options)`	Chat conversation datasets	Multi-turn chats, message arrays
`uploadExamplesMultipart()`	`({ examples with attachments })`	Large or binary data	Images, files, attachments

See Examples API for detailed documentation.

Listing Data

Method	Returns	Iteration	Best For	Performance
`listRuns()`	`AsyncIterable<Run>`	Stream	Large result sets, real-time processing	Memory efficient, no size limit
`listProjects()`	`Promise<TracerSession[]>`	Array	Small result sets, all-at-once	Fast, full array in memory
`listDatasets()`	`AsyncIterable<Dataset>`	Stream	Many datasets	Memory efficient
`listExamples()`	`AsyncIterable<Example>`	Stream	Large datasets	Memory efficient
`listFeedback()`	`AsyncIterable<Feedback>`	Stream	Many feedback items	Memory efficient
`listGroupRuns()`	`AsyncIterable<Thread>`	Stream	Grouped analytics by conversation/user	Aggregated stats, efficient
`getRunStats()`	`Promise<RunStats>`	N/A	Aggregate metrics only (no individual runs)	Fastest, minimal data transfer

Key Principle: Use AsyncIterable methods for large result sets (stream processing), Promise<array> methods for small sets.

Tracing Approaches

Approach	Control Level	Complexity	Setup	Use When
`traceable()`	Low (automatic)	Simple	1 line	Automatic function tracing
`RunTree`	High (manual)	Complex	Multiple calls	Fine-grained control, distributed tracing
`wrapOpenAI()`	Medium	Simple	1 line	OpenAI SDK integration
`wrapAnthropic()`	Medium	Simple	1 line	Anthropic SDK integration
`wrapAISDK()`	Medium	Medium	Config required	Vercel AI SDK integration
`wrapSDK()`	Low-Medium	Simple	1 line	Generic SDK, custom APIs
`getLangchainCallbacks()`	Medium	Simple	Pass callbacks	LangChain integration

Decision Flow:

Using specific SDK? → Use specialized wrapper (wrapOpenAI, etc.)
Own functions? → Use traceable()
Non-function code or custom events? → Use RunTree
Generic SDK without wrapper? → Use wrapSDK()

Querying Runs

Method	Granularity	Response Type	Use Case
`readRun(runId)`	Single run	`Promise<Run>`	Fetch specific run by ID
`listRuns({ projectName })`	Multiple runs	`AsyncIterable<Run>`	All runs in project, with filtering
`listRuns({ traceId })`	All runs in trace	`AsyncIterable<Run>`	All runs in a trace tree
`listRuns({ parentRunId })`	Children of run	`AsyncIterable<Run>`	All child runs of a parent
`listRuns({ isRoot: true })`	Root runs only	`AsyncIterable<Run>`	Top-level runs without parents
`listGroupRuns({ groupBy })`	Grouped runs	`AsyncIterable<Thread>`	Analytics by conversation/session
`getRunStats({ projectName })`	Aggregates only	`Promise<Stats>`	Summary statistics without individual runs

See Runs API for detailed filtering options.

Feedback Collection

Method	Auth Required	Use When	Security
`createFeedback()`	API key	Direct server-side access	Secure (API key required)
`createPresignedFeedbackToken()`	API key (creation only)	Public feedback collection	Token-based, time-limited
`logEvaluationFeedback()`	API key	From evaluator functions	Secure
`evaluateRun()`	API key	Single-run evaluation	Secure

Presigned tokens enable feedback collection without exposing API key - ideal for frontend/mobile apps.

Dataset Versioning

Operation	Method	Use Case
Auto-version	Add/modify examples	Automatic versioning on changes
Tag version	`updateDatasetTag({ tag, asOf })`	Label specific versions (v1, v2, prod)
Read version	`readDatasetVersion({ asOf })`	Access historical snapshot
Compare versions	`diffDatasetVersions({ from, to })`	See what changed between versions
List splits	`listDatasetSplits()`	View train/test/validation splits

Privacy Controls

Level	Method	Granularity	Flexibility
Client-wide	`new Client({ hideInputs: true })`	All traces	Boolean only
Client-wide selective	`new Client({ hideInputs: fn })`	All traces	Function transform
Client-wide patterns	`new Client({ anonymizer })`	All traces	Regex/processor rules
Per-function	`traceable(fn, { processInputs })`	Specific function	Function transform
Per-field	Anonymizer with paths	Specific fields	Path-based rules

Recommendation: Use anonymizer for pattern-based PII, hideInputs/Outputs for structural filtering.

API by Use Case

🚀 Getting Started

Client Construction - Create and configure client
Projects - Create your first project
Runs - Create your first run

📊 Data Management

Datasets: Create • List • Version
Examples: Add • Bulk Upload • Search
Prompts: Create • Pull • Version

🔍 Querying & Analytics

List Runs: Basic • Filtering • Statistics
Projects: List • Read • URLs
Feedback: Query • Create

💡 Advanced Features

Batch Operations: Await Batches • Manual Flush
Sharing: Share Runs • Share Datasets
Feedback Tokens: Presigned Tokens

Client Methods Overview

Project Operations

// Create, read, update, delete, list projects
createProject(params) → TracerSession
readProject(params) → TracerSession
updateProject(projectId, params) → TracerSession
deleteProject(params) → void
listProjects(params?) → AsyncIterable<TracerSession>
hasProject(params) → boolean
getProjectUrl(params) → string

Run Operations

// Create, read, update, list, share runs
createRun(run) → void
updateRun(runId, update) → void
readRun(runId) → Run
listRuns(params) → AsyncIterable<Run>
shareRun(runId) → string
getRunUrl(params) → string
getRunStats(params) → RunStats

Dataset Operations

// Create, read, update, delete, list, share datasets
createDataset(params) → Dataset
readDataset(params) → Dataset
updateDataset(params) → Dataset
deleteDataset(params) → void
listDatasets(params?) → AsyncIterable<Dataset>
shareDataset(datasetId) → string
indexDataset(params) → void
similarExamples(params) → Example[]

Example Operations

// Create, read, update, delete examples
createExample(example) → Example
createExamples(params) → void
updateExample(params) → Example
updateExamples(examples) → void
listExamples(params) → AsyncIterable<Example>
deleteExample(exampleId) → void

Feedback Operations

// Create, read, update, delete, list feedback
createFeedback(feedback) → Feedback
updateFeedback(feedbackId, update) → void
readFeedback(feedbackId) → Feedback
listFeedback(params) → AsyncIterable<Feedback>
deleteFeedback(feedbackId) → void
createPresignedFeedbackToken(params) → FeedbackIngestToken

Prompt Operations

// Create, pull, push, list prompts
createPrompt(name, params?) → Prompt
pullPrompt(name, params?) → PromptCommit
pushPrompt(name, params) → string
listPrompts(params?) → AsyncIterable<Prompt>
deletePrompt(name) → void
likePrompt(name) → void
unlikePrompt(name) → void

Common Patterns

Initialization

import { Client } from "langsmith";

// Default configuration
const client = new Client();

// Custom configuration
const client = new Client({
  apiKey: process.env.LANGSMITH_API_KEY,
  timeout_ms: 10000,
  autoBatchTracing: true,
});

Async Iteration

// Iterate through all results
for await (const run of client.listRuns({ projectName: "my-project" })) {
  console.log(run.name);
}

// With filtering
for await (const dataset of client.listDatasets({ datasetName: "test" })) {
  console.log(dataset.name);
}

Error Handling

try {
  const run = await client.readRun(runId);
} catch (error) {
  if (error.status === 404) {
    console.error("Run not found");
  } else if (error.status === 401) {
    console.error("Authentication failed");
  } else {
    console.error("API error:", error.message);
  }
}

Type Safety

All API methods are fully typed. Import types from langsmith/schemas:

import type {
  Run,
  RunCreate,
  Dataset,
  Example,
  Feedback,
  TracerSession,
} from "langsmith/schemas";

See Schemas for complete type reference.

Configuration Best Practices

Production Setup

const client = new Client({
  apiKey: process.env.LANGSMITH_API_KEY,
  autoBatchTracing: true,
  tracingSamplingRate: 0.1,  // 10% sampling
  hideInputs: (inputs) => redactPII(inputs),
  blockOnRootRunFinalization: false,
});

Development Setup

const client = new Client({
  apiKey: process.env.LANGSMITH_API_KEY,
  debug: true,  // Log all requests
  blockOnRootRunFinalization: true,  // Ensure traces complete
});

Serverless Setup

const client = new Client({
  apiKey: process.env.LANGSMITH_API_KEY,
  autoBatchTracing: true,
  batchSizeLimit: 10,  // Lower batch size for serverless
});

// Always flush before function ends
await client.awaitPendingTraceBatches();

Version